TheCloud/hugoDocs
1
0
Fork 0
mirror of https://github.com/gohugoio/hugoDocs.git synced 2025-09-13 15:16:52 -04:00
Code Issues Packages Projects Releases Wiki Activity

Update GitHub Pages documentation

Browse Source 
I had a bit of trouble understanding how to configure the two different
types of GitHub Pages. I have separated it into different sections to
make the distinction clearer.
This commit is contained in:
Jonathan Kinred 2017-12-17 22:16:56 +11:00 committed by Bjørn Erik Pedersen
parent 55787f09ac
commit f7c96b4b5a
1 changed files with 82 additions and 69 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

151
content/hosting-and-deployment/hosting-on-github.md
View File

@ -27,13 +27,84 @@ GitHub provides free and fast static hosting over SSL for personal, organization
2. You have a GitHub account. [Signing up][ghsignup] for GitHub is free.
3. You have a ready-to-publish Hugo website or have at least completed the [Quick Start][].
If you are working within an Organization account or want to set up a User website on GitHub and would like more information, refer to the [GitHub Pages documentation][ghorgs].
## Types of GitHub Pages
There are 2 types of GitHub Pages:
- User/Organization Pages (`https://<USERNAME|ORGANIZATION>.github.io/`)
- Project Pages (`https://<USERNAME|ORGANIZATION>.github.io/<PROJECT>/`)
Please refer to the [GitHub Pages documentation][ghorgs] to decide which type of site you would like to create as it will determine which of the below methods to use.
To create a User/Organization Pages site, follow the single method in the *GitHub User and Organization Pages* section below.
To create a Project Pages site, choose a method from the *Project Pages* section below.
## GitHub User or Organization Pages
As mentioned [the GitHub Pages documentation][ghorgs], you can host a user/organization page in addition to project pages. Here are the key differences in GitHub Pages websites for Users and Organizations:
1. You must use a `<USERNAME>.github.io` to host your **generated** content
2. Content from the `master` branch will be used to publish your GitHub Pages site
This is a much simpler setup as your Hugo files and generated content are published into two different repositories.
### Step-by-step Instructions
1. Create a `<YOUR-PROJECT>` (e.g. `blog`) repository on GitHub. This repository will contain Hugo's content and other source files.
2. Create a `<USERNAME>.github.io` GitHub repository. This is the repository that will contain the fully rendered version of your Hugo website.
3. `git clone <YOUR-PROJECT-URL> && cd <YOUR-PROJECT>`
4. Make your website work locally (`hugo server` or `hugo server -t <YOURTHEME>`) and open your browser to <http://localhost:1313>.
5. Once you are happy with the results:
* Press <kbd>Ctrl</kbd>+<kbd>C</kbd> to kill the server
* `rm -rf public` to completely remove the `public` directory
6. `git submodule add -b master git@github.com:<USERNAME>/<USERNAME>.github.io.git public`. This creates a git [submodule][]. Now when you run the `hugo` command to build your site to `public`, the created `public` directory will have a different remote origin (i.e. hosted GitHub repository). You can automate some of these steps with the following script.
### Put it Into a Script
You're almost done. You can also add a `deploy.sh` script to automate the preceding steps for you. You can also make it executable with `chmod +x deploy.sh`.
The following are the contents of the `deploy.sh` script:
```
#!/bin/bash
echo -e "\033[0;32mDeploying updates to GitHub...\033[0m"
# Build the project.
hugo # if using a theme, replace with `hugo -t <YOURTHEME>`
# Go To Public folder
cd public
# Add changes to git.
git add .
# Commit changes.
msg="rebuilding site `date`"
if [ $# -eq 1 ]
then msg="$1"
fi
git commit -m "$msg"
# Push source and build repos.
git push origin master
# Come Back up to the Project Root
cd ..
```
You can then run `./deploy.sh "Your optional commit message"` to send changes to `<USERNAME>.github.io`. Note that you likely will want to commit changes to your `<YOUR-PROJECT>` repository as well.
That's it! Your personal page should be up and running at `https://<USERNAME>.github.io` within a couple minutes.
## GitHub Project Pages
{{% note %}}
Make sure your `baseURL` key-value in your [site configuration](/getting-started/configuration/) reflects the full URL of your GitHub pages repository if you're using the default GH Pages URL (e.g., `username.github.io/myprojectname/`) and not a custom domain.
Make sure your `baseURL` key-value in your [site configuration](/getting-started/configuration/) reflects the full URL of your GitHub pages repository if you're using the default GH Pages URL (e.g., `<USERNAME>.github.io/<PROJECT>/`) and not a custom domain.
{{% /note %}}
## Deployment via `/docs` Folder on Master Branch
### Deployment of Project Pages from `/docs` folder on `master` branch
[As described in the GitHub Pages documentation][ghpfromdocs], you can deploy from a folder called `docs/` on your master branch. To effectively use this feature with Hugo, you need to change the Hugo publish directory in your [site's][config] `config.toml` and `config.yaml`, respectively:
@ -53,18 +124,18 @@ After running `hugo`, push your master branch to the remote repository and choos
The `docs/` option is the simplest approach but requires you set a publish directory in your site configuration. You cannot currently configure GitHub pages to publish from another directory on master, and not everyone prefers the output site live concomitantly with source files in version control.
{{% /note %}}
## Deployment From Your `gh-pages` Branch
### Deployment of Project Pages From Your `gh-pages` branch
You can also tell GitHub pages to treat your `master` branch as the published site or point to a separate `gh-pages` branch. The latter approach is a bit more complex but has some advantages:
* It keeps your source and generated website in different branches and therefore maintains version control history for both.
* Unlike the preceding `docs/` option, it uses the default `public` folder.
### Preparations for `gh-pages` Branch
#### Preparations for `gh-pages` Branch
These steps only need to be done once. Replace `upstream` with the name of your remote; e.g., `origin`:
#### Add the Public Folder
##### Add the `public` Folder
First, add the `public` folder to your `.gitignore` file at the project root so that the directory is ignored on the master branch:
@ -72,7 +143,7 @@ First, add the `public` folder to your `.gitignore` file at the project root so
echo "public" >> .gitignore
```
#### Initialize Your `gh-pages` Branch
##### Initialize Your `gh-pages` Branch
You can now initialize your `gh-pages` branch as an empty [orphan branch][]:
@ -84,7 +155,7 @@ git push upstream gh-pages
git checkout master
```
### Build and Deployment
#### Build and Deployment
Now check out the `gh-pages` branch into your `public` folder using git's [worktree feature][]. Essentially, the worktree allows you to have multiple branches of the same local repository to be checked out in different directories:
@ -106,7 +177,7 @@ If the changes in your local `gh-pages` branch look alright, push them to the re
git push upstream gh-pages
```
#### Set `gh-pages` as Your Publish Branch
##### Set `gh-pages` as Your Publish Branch
In order to use your `gh-pages` branch as your publishing branch, you'll need to configure the repository within the GitHub UI. This will likely happen automatically once GitHub realizes you've created this branch. You can also set the branch manually from within your GitHub project:
@ -115,7 +186,7 @@ In order to use your `gh-pages` branch as your publishing branch, you'll need to
After a short while, you'll see the updated contents on your GitHub Pages site.
### Put it Into a Script
#### Put it Into a Script
To automate these steps, you can create a script with the following contents:
@ -153,7 +224,7 @@ cd public && git add --all && git commit -m "Publishing to gh-pages (publish.sh)
This will abort if there are pending changes in the working directory and also makes sure that all previously existing output files are removed. Adjust the script to taste, e.g. to include the final push to the remote repository if you don't need to take a look at the gh-pages branch before pushing. Or adding `echo yourdomainname.com >> CNAME` if you set up for your gh-pages to use customize domain.
## Deployment From Your `master` Branch
### Deployment of Project Pages from Your `master` Branch
To use `master` as your publishing branch, you'll need your rendered website to live at the root of the GitHub repository. Steps should be similar to that of the `gh-pages` branch, with the exception that you will create your GitHub repository with the `public` directory as the root. Note that this does not provide the same benefits of the `gh-pages` branch in keeping your source and output in separate, but version controlled, branches within the same repo.
@ -162,64 +233,6 @@ You will also need to set `master` as your publishable branch from within the Gi
1. Go to **Settings** &rarr; **GitHub Pages**
2. From **Source**, select "master branch" and then **Save**.
## Host GitHub User or Organization Pages
As mentioned [in this GitHub Help article](https://help.github.com/articles/user-organization-and-project-pages/), you can host a user/organization page in addition to project pages. Here are the key differences in GitHub Pages websites for Users and Organizations:
1. You must use the `<USERNAME>.github.io` naming scheme for your GitHub repo.
2. Content from the `master` branch will be used to publish your GitHub Pages site.
It becomes much simpler in this case: we'll create two separate repos, one for Hugo's content, and a git submodule with the `public` folder's content in it.
### Step-by-step Instructions
1. Create a `<YOUR-PROJECT>` git repository on GitHub. This repository will contain Hugo's content and other source files.
2. Create a `<USERNAME>.github.io` GitHub repository. This is the repository that will contain the fully rendered version of your Hugo website.
3. `git clone <YOUR-PROJECT-URL> && cd <YOUR-PROJECT>`
4. Make your website work locally (`hugo server` or `hugo server -t <YOURTHEME>`) and open your browser to <http://localhost:1313>.
5. Once you are happy with the results:
* Press <kbd>Ctrl</kbd>+<kbd>C</kbd> to kill the server
* `rm -rf public` to completely remove the `public` directory if there
6. `git submodule add -b master git@github.com:<USERNAME>/<USERNAME>.github.io.git public`. This creates a git [submodule][]. Now when you run the `hugo` command to build your site to `public`, the created `public` directory will have a different remote origin (i.e. hosted GitHub repository). You can automate some of these steps with the following script.
#### Put it Into a Script
You're almost done. You can also add a `deploy.sh` script to automate the preceding steps for you. You can also make it executable with `chmod +x deploy.sh`.
The following are the contents of the `deploy.sh` script:
```
#!/bin/bash
echo -e "\033[0;32mDeploying updates to GitHub...\033[0m"
# Build the project.
hugo # if using a theme, replace with `hugo -t <YOURTHEME>`
# Go To Public folder
cd public
# Add changes to git.
git add .
# Commit changes.
msg="rebuilding site `date`"
if [ $# -eq 1 ]
then msg="$1"
fi
git commit -m "$msg"
# Push source and build repos.
git push origin master
# Come Back up to the Project Root
cd ..
```
You can then run `./deploy.sh "Your optional commit message"` to send changes to `<USERNAME>.github.io`. Note that you likely will want to commit changes to your `<YOUR-PROJECT>` repository as well.
That's it! Your personal page should be up and running at `https://yourusername.github.io` within a couple minutes.
## Use a Custom Domain
If you'd like to use a custom domain for your GitHub Pages site, create a file `static/CNAME`. Your custom domain name should be the only contents inside `CNAME`. Since it's inside `static`, the published site will contain the CNAME file at the root of the published site, which is a requirements of GitHub Pages.