mirror of
https://github.com/facebook/docusaurus.git
synced 2025-08-03 08:49:51 +02:00
docs: reword publish to GitHub Pages documentation (#1049)
* doc: Updating Using GitHub Pages Documentation * docs: Rewording deploying to github pages * docs: Review changes * Update getting-started-publishing.md
This commit is contained in:
M4rk9696
Yangshun Tay
parent
e02e0a9b92
commit
d1ced5ca13
1 changed files with 35 additions and 22 deletions
|
|
@ -30,44 +30,50 @@ At this point, you can grab all of the files inside the `website/build` director
|
|||
|
||||
### 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](https://pages.github.com/).
|
||||
Docusaurus was designed to work really well with one of the most popular hosting solutions for open source projects: [GitHub Pages](https://pages.github.com/).
|
||||
|
||||
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.
|
||||
#### Deploying to GitHub Pages
|
||||
|
||||
1. Docusaurus supports deploying as [project pages or user/organization pages](https://help.github.com/articles/user-organization-and-project-pages), your code repository does not even need to be public.
|
||||
|
||||
> Even if your repository is private, anything published to a `gh-pages` branch will be [public](https://help.github.com/articles/user-organization-and-project-pages/).
|
||||
|
||||
Most of the work to publish to GitHub pages is done for you automatically through the [`publish-gh-pages`](./api-commands.md#docusaurus-publish) script. You just need to determine the values for a few parameters required by the script.
|
||||
__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).
|
||||
|
||||
The following parameters need to be set in the [`siteConfig.js`](api-site-config.md):
|
||||
2. You will need to modify the file `website/siteConfig.js` and add the required parameters.
|
||||
|
||||
| Name | Description |
|
||||
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `organizationName` | The GitHub user or organization that owns the repository. In the case of Docusaurus, that would be the "facebook" GitHub organization. |
|
||||
| `projectName` | The 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". |
|
||||
| `organizationName` | 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 "_facebook_" GitHub organization. |
|
||||
| `projectName` | The 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". |
|
||||
| `url` | Your website's URL. For projects hosted on GitHub pages, this will be "https://_username_.github.io" |
|
||||
| `baseUrl` | Base 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](https://help.github.com/articles/user-organization-and-project-pages/#user--organization-pages). 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).
|
||||
|
||||
```js
|
||||
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 "<username>.github.io" or "<orgname>.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:
|
||||
3. Now you have to specify the git user as an environment variable, and run the script [`publish-gh-pages`](./api-commands.md#docusaurus-publish)
|
||||
|
||||
| Name | Description |
|
||||
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `GIT_USER` | 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. |
|
||||
| `GIT_USER` | 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 `GIT_USER` must have push access to the repository specified in the combination of `organizationName` and `projectName`. |
|
||||
|
||||
There are also two optional parameters that are set as environment variables:
|
||||
|
||||
| Name | Description |
|
||||
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `USE_SSH` | If this is set to `true`, then SSH is used instead of HTTPS for the connection to the GitHub repo. HTTPS is the default if this variable is not set. |
|
||||
| `CURRENT_BRANCH` | The 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](https://help.github.com/articles/connecting-to-github-with-ssh/).
|
||||
To run the script directly from the command-line, you can use the following, filling in the parameter values as appropriate.
|
||||
|
||||
```bash
|
||||
GIT_USER=<GIT_USER> \
|
||||
|
|
@ -76,9 +82,16 @@ GIT_USER=<GIT_USER> \
|
|||
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`.
|
||||
There are also two optional parameters that are set as environment variables:
|
||||
|
||||
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](https://pages.github.com) to learn more about how this hosting solution works.
|
||||
| Name | Description |
|
||||
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `USE_SSH` | If this is set to `true`, then SSH is used instead of HTTPS for the connection to the GitHub repo. HTTPS is the default if this variable is not set. |
|
||||
| `CURRENT_BRANCH` | The 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. |
|
||||
|
||||
If you run into issues related to SSH keys, visit [GitHub's authentication documentation](https://help.github.com/articles/connecting-to-github-with-ssh/).
|
||||
|
||||
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](https://pages.github.com) 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.
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue