diff --git a/docs/en/next/publishing.html b/docs/en/next/publishing.html index 31c0688961..282a2cfcbd 100644 --- a/docs/en/next/publishing.html +++ b/docs/en/next/publishing.html @@ -71,40 +71,60 @@
  • Netlify

    • Using GitHub Pages

    -

    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: GitHub Pages.

    -

    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.

    +

    Docusaurus was designed to work really well with one of the most popular hosting solutions for open source projects: GitHub Pages.

    +

    Deploying to GitHub Pages

    +
      +
    1. Docusaurus supports deploying as project pages or user/organization pages, your code repository does not even need to be public.
      2. +

    Even if your repository is private, anything published to a gh-pages branch will be public.

    -

    Most of the work to publish to GitHub pages is done for you automatically through the publish-gh-pages script. You just need to determine the values for a few parameters required by the script.

    -

    The following parameters need to be set in the siteConfig.js:

    +

    Note: When you deploy as user/organization page, the publish script will deploy these sites to the root of the master branch of the username.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 username.github.io repo (e.g., maybe call it source), or in another, separate repo (e.g. in the same as the documented source code).

    +
      +
    1. You will need to modify the file website/siteConfig.js and add the required parameters.
      2. +
    - - + +
    NameDescription
    organizationNameThe GitHub user or organization that owns the repository. In the case of Docusaurus, that would be the "facebook" GitHub organization.
    projectNameThe name of the GitHub repository for your project. For example, Docusaurus is hosted at https://github.com/facebook/docusaurus, so our project name in this case would be "docusaurus".
    organizationNameThe 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 "facebook" GitHub organization.
    projectNameThe name of the GitHub repository for your project. For example, the source code for Docusaurus is hosted at https://github.com/facebook/docusaurus, so our project name in this case would be "docusaurus".
    urlYour website's URL. For projects hosted on GitHub pages, this will be "https://username.github.io"
    baseUrlBase URL for your project. For projects hosted on GitHub pages, it follows the format "/projectName/". For https://github.com/facebook/docusaurus, baseUrl is /docusaurus/.
    -
    -

    Docusaurus also supports deploying user or organization sites. To do this, just set projectName to "username.github.io" (where username is your username or organization name on GitHub) and organizationName to "username".
    -For user or org sites, the publish script will deploy these sites to the root of the master branch of the username.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 username.github.io repo (e.g., maybe call it source), or in another, separated repo (e.g. in the same as the documented source code).

    -
    +
    const siteConfig = {
+  ...
+  url: 'https://__userName__.github.io', // Your website URL
+  baseUrl: '/testProject',
+  projectName: 'testProject',
+  organizationName: 'userName'
+  ...
+}
+
    +

    In case you want to deploy as a user or organization site, specify the project name as ".github.io" or ".github.io". E.g. If your GitHub username is "user42" then user42.github.io, or in the case of an organization name of "org123", it will be org123.github.io.

    +

    Note: Not setting the url and baseUrl of your project might result in incorrect file paths generated which can cause broken links to assets paths like stylesheets and images.

    While we recommend setting the projectName and organizationName in siteConfig.js, you can also use environment variables ORGANIZATION_NAME and PROJECT_NAME.

    -

    One of the required parameters is set as a environment variable:

    +
      +
    1. Now you have to specify the git user as an environment variable, and run the script publish-gh-pages
      2. +
    - +
    NameDescription
    GIT_USERThe username for a GitHub account that has commit access to this repo. For your own repositories, this will usually be your own GitHub username.
    GIT_USERThe 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 GIT_USER must have push access to the repository specified in the combination of organizationName and projectName.
    +

    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 \
+  USE_SSH=true \
+  yarn run publish-gh-pages # or `npm run publish-gh-pages`
+

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

    @@ -115,17 +135,8 @@ For user or org sites, the publish script will deploy these sites to the root of
    CURRENT_BRANCHThe branch that contains the latest docs changes that will be deployed. Usually, the branch will be master, but it could be any branch (default or otherwise) except for gh-pages. If nothing is set for this variable, then the current branch will be used.
    -

    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. If you run into issues related to SSH keys, visit GitHub's authentication documentation.

    -
    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.

    -
    -

    You should now be able to load your website by visiting its GitHub Pages URL, which could be something along the lines of https://username.github.io/projectName, or a custom domain if you have set that up. For example, Docusaurus' own GitHub Pages URL is https://facebook.github.io/Docusaurus (it can also be accessed via https://docusaurus.io/), because it is served from the gh-pages branch of the https://github.com/facebook/docusaurus GitHub repository. We highly encourage reading through the GitHub Pages documentation to learn more about how this hosting solution works.

    +

    If you run into issues related to SSH keys, visit GitHub's authentication documentation.

    +

    You should now be able to load your website by visiting its GitHub Pages URL, which could be something along the lines of https://username.github.io/projectName, or a custom domain if you have set that up. For example, Docusaurus' own GitHub Pages URL is https://facebook.github.io/Docusaurus (but it can also be accessed via https://docusaurus.io/ because of a CNAME), because it is served from the gh-pages branch of the https://github.com/facebook/docusaurus GitHub repository. We highly encourage reading through the GitHub Pages documentation to learn more about how this hosting solution works.

    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.

    However, you can automate the publishing process with continuous integration (CI).

    Automating Deployments Using Continuous Integration

    @@ -249,7 +260,7 @@ For user or org sites, the publish script will deploy these sites to the root of

    Alter your siteConfig.js to add a property 'githubHost' which represents the GitHub Enterprise hostname. Alternatively, set an environment variable GITHUB_HOST when executing the publish command.

    -
    Last updated on 2018-10-15 by Alex Driedger
    ← PreviousNext →