mirror of
https://github.com/facebook/docusaurus.git
synced 2025-06-05 12:22:45 +02:00
Website Deployment Script
parent
9e26ebd4d7
commit
4cbf35b0ee
2 changed files with 70 additions and 48 deletions
|
|
@ -71,40 +71,60 @@
|
|||
<li><a href="#hosting-on-netlify">Netlify</a></li>
|
||||
</ul>
|
||||
<h3><a class="anchor" aria-hidden="true" id="using-github-pages"></a><a href="#using-github-pages" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" 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>Using GitHub Pages</h3>
|
||||
<p>While choosing a web server or host is outside Docusaurus' scope, Docusaurus was designed to work really well with one of the most popular hosting solutions for open source projects: <a href="https://pages.github.com/">GitHub Pages</a>.</p>
|
||||
<p>Deploying your Docusaurus site to GitHub Pages is straightforward if you are already using GitHub to host your project. Your code repository does not even need to be public.</p>
|
||||
<p>Docusaurus was designed to work really well with one of the most popular hosting solutions for open source projects: <a href="https://pages.github.com/">GitHub Pages</a>.</p>
|
||||
<h4><a class="anchor" aria-hidden="true" id="deploying-to-github-pages"></a><a href="#deploying-to-github-pages" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" 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>Deploying to GitHub Pages</h4>
|
||||
<ol>
|
||||
<li>Docusaurus supports deploying as <a href="https://help.github.com/articles/user-organization-and-project-pages">project pages or user/organization pages</a>, your code repository does not even need to be public.</li>
|
||||
</ol>
|
||||
<blockquote>
|
||||
<p>Even if your repository 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="/docs/en/next/commands#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>The following parameters need to be set in the <a href="/docs/en/next/site-config"><code>siteConfig.js</code></a>:</p>
|
||||
<p><strong>Note:</strong> When you deploy as user/organization page, the publish script will deploy these sites to the root of the <strong><code>master</code></strong> branch of the <em>username</em>.github.io repo. In this case, note that you will want to have the Docusaurus infra, your docs, etc. either in <strong>another branch of the <em>username</em>.github.io repo</strong> (e.g., maybe call it <code>source</code>), or in another, separate repo (e.g. in the same as the documented source code).</p>
|
||||
<ol start="2">
|
||||
<li>You will need to modify the file <code>website/siteConfig.js</code> and add the required parameters.</li>
|
||||
</ol>
|
||||
<table>
|
||||
<thead>
|
||||
<tr><th>Name</th><th>Description</th></tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr><td><code>organizationName</code></td><td>The GitHub user or organization that owns the repository. In the case of Docusaurus, that would be the "facebook" GitHub organization.</td></tr>
|
||||
<tr><td><code>projectName</code></td><td>The name of the GitHub repository for your project. For example, Docusaurus is hosted at <a href="https://github.com/facebook/docusaurus">https://github.com/facebook/docusaurus</a>, so our project name in this case would be "docusaurus".</td></tr>
|
||||
<tr><td><code>organizationName</code></td><td>The GitHub user or organization that owns the repository. If you are the owner, then it is your GitHub username. In the case of Docusaurus, that would be the "<em>facebook</em>" GitHub organization.</td></tr>
|
||||
<tr><td><code>projectName</code></td><td>The name of the GitHub repository for your project. For example, the source code for Docusaurus is hosted at <a href="https://github.com/facebook/docusaurus">https://github.com/facebook/docusaurus</a>, so our project name in this case would be "docusaurus".</td></tr>
|
||||
<tr><td><code>url</code></td><td>Your website's URL. For projects hosted on GitHub pages, this will be "https://<em>username</em>.github.io"</td></tr>
|
||||
<tr><td><code>baseUrl</code></td><td>Base URL for your project. For projects hosted on GitHub pages, it follows the format "/<em>projectName</em>/". For <a href="https://github.com/facebook/docusaurus">https://github.com/facebook/docusaurus</a>, <code>baseUrl</code> is <code>/docusaurus/</code>.</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<blockquote>
|
||||
<p>Docusaurus also supports deploying <a href="https://help.github.com/articles/user-organization-and-project-pages/#user--organization-pages">user or organization sites</a>. To do this, just set <code>projectName</code> to "<em>username</em>.github.io" (where <em>username</em> is your username or organization name on GitHub) and <code>organizationName</code> to "<em>username</em>".<br>
|
||||
For user or org sites, the publish script will deploy these sites to the root of the <code>master</code> branch of the <em>username</em>.github.io repo. In this case, note that you will want to have the Docusaurus infra, your docs, etc. either in another branch of the <em>username</em>.github.io repo (e.g., maybe call it <code>source</code>), or in another, separated repo (e.g. in the same as the documented source code).</p>
|
||||
</blockquote>
|
||||
<pre><code class="hljs css language-js"><span class="hljs-keyword">const</span> siteConfig = {
|
||||
...
|
||||
url: <span class="hljs-string">'https://__userName__.github.io'</span>, <span class="hljs-comment">// Your website URL</span>
|
||||
baseUrl: <span class="hljs-string">'/testProject'</span>,
|
||||
<span class="hljs-attr">projectName</span>: <span class="hljs-string">'testProject'</span>,
|
||||
<span class="hljs-attr">organizationName</span>: <span class="hljs-string">'userName'</span>
|
||||
...
|
||||
}
|
||||
</code></pre>
|
||||
<p>In case you want to deploy as a user or organization site, specify the project name as "<username>.github.io" or "<orgname>.github.io". E.g. If your GitHub username is "user42" then <em>user42.github.io</em>, or in the case of an organization name of "org123", it will be <em>org123.github.io</em>.</p>
|
||||
<p><strong>Note:</strong> Not setting the <code>url</code> and <code>baseUrl</code> of your project might result in incorrect file paths generated which can cause broken links to assets paths like stylesheets and images.</p>
|
||||
<blockquote>
|
||||
<p>While we recommend setting the <code>projectName</code> and <code>organizationName</code> 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 is set as a environment variable:</p>
|
||||
<ol start="3">
|
||||
<li>Now you have to specify the git user as an environment variable, and run the script <a href="/docs/en/next/commands#docusaurus-publish"><code>publish-gh-pages</code></a></li>
|
||||
</ol>
|
||||
<table>
|
||||
<thead>
|
||||
<tr><th>Name</th><th>Description</th></tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr><td><code>GIT_USER</code></td><td>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.</td></tr>
|
||||
<tr><td><code>GIT_USER</code></td><td>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. 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>.</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<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 css language-bash">GIT_USER=<GIT_USER> \
|
||||
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>
|
||||
<p>There are also two optional parameters that are set as environment variables:</p>
|
||||
<table>
|
||||
<thead>
|
||||
|
|
@ -115,17 +135,8 @@ For user or org sites, the publish script will deploy these sites to the root of
|
|||
<tr><td><code>CURRENT_BRANCH</code></td><td>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.</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<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. If you run into issues related to SSH keys, visit <a href="https://help.github.com/articles/connecting-to-github-with-ssh/">GitHub's authentication documentation</a>.</p>
|
||||
<pre><code class="hljs css language-bash">GIT_USER=<GIT_USER> \
|
||||
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>
|
||||
</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 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://facebook.github.io/Docusaurus">https://facebook.github.io/Docusaurus</a> (it can also be accessed via <a href="https://docusaurus.io/">https://docusaurus.io/</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 repository. 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>If you run into issues related to SSH keys, visit <a href="https://help.github.com/articles/connecting-to-github-with-ssh/">GitHub's authentication documentation</a>.</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://facebook.github.io/Docusaurus">https://facebook.github.io/Docusaurus</a> (but it can also be accessed via <a href="https://docusaurus.io/">https://docusaurus.io/</a> because of a CNAME), 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 repository. 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" id="automating-deployments-using-continuous-integration"></a><a href="#automating-deployments-using-continuous-integration" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" 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>
|
||||
|
|
@ -249,7 +260,7 @@ For user or org sites, the publish script will deploy these sites to the root of
|
|||
</tbody>
|
||||
</table>
|
||||
<p>Alter your <code>siteConfig.js</code> to add a property <code>'githubHost'</code> which represents the GitHub Enterprise hostname. Alternatively, set an environment variable <code>GITHUB_HOST</code> when executing the publish command.</p>
|
||||
</span></div></article></div><div class="docLastUpdate"><em>Last updated on 2018-10-15 by Alex Driedger</em></div><div class="docs-prevnext"><a class="docs-prev button" href="/docs/en/next/site-creation"><span class="arrow-prev">← </span><span>Previous</span></a><a class="docs-next button" href="/docs/en/next/docker"><span>Next</span><span class="arrow-next"> →</span></a></div></div></div><nav class="onPageNav docOnPageNav"><ul class="toc-headings"><li><a href="#building-static-html-pages">Building Static HTML Pages</a></li><li><a href="#hosting-static-html-pages">Hosting Static HTML Pages</a><ul class="toc-headings"><li><a href="#hosting-on-a-service">Hosting on a Service:</a></li><li><a href="#using-github-pages">Using GitHub Pages</a></li></ul></li><li><a href="#automating-deployments-using-continuous-integration">Automating Deployments Using Continuous Integration</a><ul class="toc-headings"><li><a href="#using-circle-ci-20">Using Circle CI 2.0</a></li><li><a href="#tips-tricks">Tips & Tricks</a></li><li><a href="#using-travis-ci">Using Travis CI</a></li><li><a href="#hosting-on-netlify">Hosting on Netlify</a></li><li><a href="#publishing-to-github-enterprise">Publishing to GitHub Enterprise</a></li></ul></li></ul></nav></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 class="footerSection"><h5>Docs</h5><a href="
|
||||
</span></div></article></div><div class="docLastUpdate"><em>Last updated on 2018-10-21 by M4rk9696</em></div><div class="docs-prevnext"><a class="docs-prev button" href="/docs/en/next/site-creation"><span class="arrow-prev">← </span><span>Previous</span></a><a class="docs-next button" href="/docs/en/next/docker"><span>Next</span><span class="arrow-next"> →</span></a></div></div></div><nav class="onPageNav docOnPageNav"><ul class="toc-headings"><li><a href="#building-static-html-pages">Building Static HTML Pages</a></li><li><a href="#hosting-static-html-pages">Hosting Static HTML Pages</a><ul class="toc-headings"><li><a href="#hosting-on-a-service">Hosting on a Service:</a></li><li><a href="#using-github-pages">Using GitHub Pages</a></li></ul></li><li><a href="#automating-deployments-using-continuous-integration">Automating Deployments Using Continuous Integration</a><ul class="toc-headings"><li><a href="#using-circle-ci-20">Using Circle CI 2.0</a></li><li><a href="#tips-tricks">Tips & Tricks</a></li><li><a href="#using-travis-ci">Using Travis CI</a></li><li><a href="#hosting-on-netlify">Hosting on Netlify</a></li><li><a href="#publishing-to-github-enterprise">Publishing to GitHub Enterprise</a></li></ul></li></ul></nav></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 class="footerSection"><h5>Docs</h5><a href="
|
||||
/docs/en/installation">Getting Started</a><a href="
|
||||
/docs/en/versioning">Versioning</a><a href="
|
||||
/docs/en/translation">Localization</a><a href="
|
||||
|
|
|
|||
|
|
@ -71,40 +71,60 @@
|
|||
<li><a href="#hosting-on-netlify">Netlify</a></li>
|
||||
</ul>
|
||||
<h3><a class="anchor" aria-hidden="true" id="using-github-pages"></a><a href="#using-github-pages" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" 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>Using GitHub Pages</h3>
|
||||
<p>While choosing a web server or host is outside Docusaurus' scope, Docusaurus was designed to work really well with one of the most popular hosting solutions for open source projects: <a href="https://pages.github.com/">GitHub Pages</a>.</p>
|
||||
<p>Deploying your Docusaurus site to GitHub Pages is straightforward if you are already using GitHub to host your project. Your code repository does not even need to be public.</p>
|
||||
<p>Docusaurus was designed to work really well with one of the most popular hosting solutions for open source projects: <a href="https://pages.github.com/">GitHub Pages</a>.</p>
|
||||
<h4><a class="anchor" aria-hidden="true" id="deploying-to-github-pages"></a><a href="#deploying-to-github-pages" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" 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>Deploying to GitHub Pages</h4>
|
||||
<ol>
|
||||
<li>Docusaurus supports deploying as <a href="https://help.github.com/articles/user-organization-and-project-pages">project pages or user/organization pages</a>, your code repository does not even need to be public.</li>
|
||||
</ol>
|
||||
<blockquote>
|
||||
<p>Even if your repository 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="/docs/en/next/commands#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>The following parameters need to be set in the <a href="/docs/en/next/site-config"><code>siteConfig.js</code></a>:</p>
|
||||
<p><strong>Note:</strong> When you deploy as user/organization page, the publish script will deploy these sites to the root of the <strong><code>master</code></strong> branch of the <em>username</em>.github.io repo. In this case, note that you will want to have the Docusaurus infra, your docs, etc. either in <strong>another branch of the <em>username</em>.github.io repo</strong> (e.g., maybe call it <code>source</code>), or in another, separate repo (e.g. in the same as the documented source code).</p>
|
||||
<ol start="2">
|
||||
<li>You will need to modify the file <code>website/siteConfig.js</code> and add the required parameters.</li>
|
||||
</ol>
|
||||
<table>
|
||||
<thead>
|
||||
<tr><th>Name</th><th>Description</th></tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr><td><code>organizationName</code></td><td>The GitHub user or organization that owns the repository. In the case of Docusaurus, that would be the "facebook" GitHub organization.</td></tr>
|
||||
<tr><td><code>projectName</code></td><td>The name of the GitHub repository for your project. For example, Docusaurus is hosted at <a href="https://github.com/facebook/docusaurus">https://github.com/facebook/docusaurus</a>, so our project name in this case would be "docusaurus".</td></tr>
|
||||
<tr><td><code>organizationName</code></td><td>The GitHub user or organization that owns the repository. If you are the owner, then it is your GitHub username. In the case of Docusaurus, that would be the "<em>facebook</em>" GitHub organization.</td></tr>
|
||||
<tr><td><code>projectName</code></td><td>The name of the GitHub repository for your project. For example, the source code for Docusaurus is hosted at <a href="https://github.com/facebook/docusaurus">https://github.com/facebook/docusaurus</a>, so our project name in this case would be "docusaurus".</td></tr>
|
||||
<tr><td><code>url</code></td><td>Your website's URL. For projects hosted on GitHub pages, this will be "https://<em>username</em>.github.io"</td></tr>
|
||||
<tr><td><code>baseUrl</code></td><td>Base URL for your project. For projects hosted on GitHub pages, it follows the format "/<em>projectName</em>/". For <a href="https://github.com/facebook/docusaurus">https://github.com/facebook/docusaurus</a>, <code>baseUrl</code> is <code>/docusaurus/</code>.</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<blockquote>
|
||||
<p>Docusaurus also supports deploying <a href="https://help.github.com/articles/user-organization-and-project-pages/#user--organization-pages">user or organization sites</a>. To do this, just set <code>projectName</code> to "<em>username</em>.github.io" (where <em>username</em> is your username or organization name on GitHub) and <code>organizationName</code> to "<em>username</em>".<br>
|
||||
For user or org sites, the publish script will deploy these sites to the root of the <code>master</code> branch of the <em>username</em>.github.io repo. In this case, note that you will want to have the Docusaurus infra, your docs, etc. either in another branch of the <em>username</em>.github.io repo (e.g., maybe call it <code>source</code>), or in another, separated repo (e.g. in the same as the documented source code).</p>
|
||||
</blockquote>
|
||||
<pre><code class="hljs css language-js"><span class="hljs-keyword">const</span> siteConfig = {
|
||||
...
|
||||
url: <span class="hljs-string">'https://__userName__.github.io'</span>, <span class="hljs-comment">// Your website URL</span>
|
||||
baseUrl: <span class="hljs-string">'/testProject'</span>,
|
||||
<span class="hljs-attr">projectName</span>: <span class="hljs-string">'testProject'</span>,
|
||||
<span class="hljs-attr">organizationName</span>: <span class="hljs-string">'userName'</span>
|
||||
...
|
||||
}
|
||||
</code></pre>
|
||||
<p>In case you want to deploy as a user or organization site, specify the project name as "<username>.github.io" or "<orgname>.github.io". E.g. If your GitHub username is "user42" then <em>user42.github.io</em>, or in the case of an organization name of "org123", it will be <em>org123.github.io</em>.</p>
|
||||
<p><strong>Note:</strong> Not setting the <code>url</code> and <code>baseUrl</code> of your project might result in incorrect file paths generated which can cause broken links to assets paths like stylesheets and images.</p>
|
||||
<blockquote>
|
||||
<p>While we recommend setting the <code>projectName</code> and <code>organizationName</code> 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 is set as a environment variable:</p>
|
||||
<ol start="3">
|
||||
<li>Now you have to specify the git user as an environment variable, and run the script <a href="/docs/en/next/commands#docusaurus-publish"><code>publish-gh-pages</code></a></li>
|
||||
</ol>
|
||||
<table>
|
||||
<thead>
|
||||
<tr><th>Name</th><th>Description</th></tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr><td><code>GIT_USER</code></td><td>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.</td></tr>
|
||||
<tr><td><code>GIT_USER</code></td><td>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. 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>.</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<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 css language-bash">GIT_USER=<GIT_USER> \
|
||||
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>
|
||||
<p>There are also two optional parameters that are set as environment variables:</p>
|
||||
<table>
|
||||
<thead>
|
||||
|
|
@ -115,17 +135,8 @@ For user or org sites, the publish script will deploy these sites to the root of
|
|||
<tr><td><code>CURRENT_BRANCH</code></td><td>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.</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<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. If you run into issues related to SSH keys, visit <a href="https://help.github.com/articles/connecting-to-github-with-ssh/">GitHub's authentication documentation</a>.</p>
|
||||
<pre><code class="hljs css language-bash">GIT_USER=<GIT_USER> \
|
||||
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>
|
||||
</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 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://facebook.github.io/Docusaurus">https://facebook.github.io/Docusaurus</a> (it can also be accessed via <a href="https://docusaurus.io/">https://docusaurus.io/</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 repository. 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>If you run into issues related to SSH keys, visit <a href="https://help.github.com/articles/connecting-to-github-with-ssh/">GitHub's authentication documentation</a>.</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://facebook.github.io/Docusaurus">https://facebook.github.io/Docusaurus</a> (but it can also be accessed via <a href="https://docusaurus.io/">https://docusaurus.io/</a> because of a CNAME), 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 repository. 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" id="automating-deployments-using-continuous-integration"></a><a href="#automating-deployments-using-continuous-integration" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" 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>
|
||||
|
|
@ -249,7 +260,7 @@ For user or org sites, the publish script will deploy these sites to the root of
|
|||
</tbody>
|
||||
</table>
|
||||
<p>Alter your <code>siteConfig.js</code> to add a property <code>'githubHost'</code> which represents the GitHub Enterprise hostname. Alternatively, set an environment variable <code>GITHUB_HOST</code> when executing the publish command.</p>
|
||||
</span></div></article></div><div class="docLastUpdate"><em>Last updated on 2018-10-15 by Alex Driedger</em></div><div class="docs-prevnext"><a class="docs-prev button" href="/docs/en/next/site-creation"><span class="arrow-prev">← </span><span>Previous</span></a><a class="docs-next button" href="/docs/en/next/docker"><span>Next</span><span class="arrow-next"> →</span></a></div></div></div><nav class="onPageNav docOnPageNav"><ul class="toc-headings"><li><a href="#building-static-html-pages">Building Static HTML Pages</a></li><li><a href="#hosting-static-html-pages">Hosting Static HTML Pages</a><ul class="toc-headings"><li><a href="#hosting-on-a-service">Hosting on a Service:</a></li><li><a href="#using-github-pages">Using GitHub Pages</a></li></ul></li><li><a href="#automating-deployments-using-continuous-integration">Automating Deployments Using Continuous Integration</a><ul class="toc-headings"><li><a href="#using-circle-ci-20">Using Circle CI 2.0</a></li><li><a href="#tips-tricks">Tips & Tricks</a></li><li><a href="#using-travis-ci">Using Travis CI</a></li><li><a href="#hosting-on-netlify">Hosting on Netlify</a></li><li><a href="#publishing-to-github-enterprise">Publishing to GitHub Enterprise</a></li></ul></li></ul></nav></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 class="footerSection"><h5>Docs</h5><a href="
|
||||
</span></div></article></div><div class="docLastUpdate"><em>Last updated on 2018-10-21 by M4rk9696</em></div><div class="docs-prevnext"><a class="docs-prev button" href="/docs/en/next/site-creation"><span class="arrow-prev">← </span><span>Previous</span></a><a class="docs-next button" href="/docs/en/next/docker"><span>Next</span><span class="arrow-next"> →</span></a></div></div></div><nav class="onPageNav docOnPageNav"><ul class="toc-headings"><li><a href="#building-static-html-pages">Building Static HTML Pages</a></li><li><a href="#hosting-static-html-pages">Hosting Static HTML Pages</a><ul class="toc-headings"><li><a href="#hosting-on-a-service">Hosting on a Service:</a></li><li><a href="#using-github-pages">Using GitHub Pages</a></li></ul></li><li><a href="#automating-deployments-using-continuous-integration">Automating Deployments Using Continuous Integration</a><ul class="toc-headings"><li><a href="#using-circle-ci-20">Using Circle CI 2.0</a></li><li><a href="#tips-tricks">Tips & Tricks</a></li><li><a href="#using-travis-ci">Using Travis CI</a></li><li><a href="#hosting-on-netlify">Hosting on Netlify</a></li><li><a href="#publishing-to-github-enterprise">Publishing to GitHub Enterprise</a></li></ul></li></ul></nav></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 class="footerSection"><h5>Docs</h5><a href="
|
||||
/docs/en/installation">Getting Started</a><a href="
|
||||
/docs/en/versioning">Versioning</a><a href="
|
||||
/docs/en/translation">Localization</a><a href="
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue