blogs/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2026-08-26 00:08:53 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update GitHub pages hosting

Browse Source 
Closes rdwatters/hugo-docs-concept#60
This commit is contained in:
Ryan Watters
2017-03-30 15:38:26 -05:00
parent b286c7d9a0
commit 5758a6d68b
1 changed files with 91 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/hosting-and-deployment/hosting-on-github.md
+91 -48
View File
@@ -14,17 +14,19 @@ toc: true
aliases: [/tutorials/github-pages-blog/]
---
{{% note %}}
This hosting and deployment guide was originally contributed as a tutorial by [Spencer Lyon](http://spencerlyon.com/) and [Gunnar Morling](https://github.com/gunnarmorling/).
{{% /note %}}
GitHub provides free and fast static hosting over SSL for personal, organization, or project pages directly from a GitHub repository via its [GitHub Pages service][].
## Assumptions
The following sections are based on the assumption that you are working with a "Project Pages Site." This means that you'll have your Hugo source and the generated HTML output within a single repository. In contrast with a "User/Organization Page Site", you're going to have one repo for the sources and another repo for the published HTML files. For more information on Organization Pages, refer to the [GitHub Pages docs](https://help.github.com/articles/user-organization-and-project-pages/) to learn more).
1. You have a GitHub account. [Signing up][ghsignup] for GitHub is free.
2. You are working with a "GitHub Project Pages Site", which means you'll have your Hugo source and generated HTML output within a single repository.
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].
## Deployment via `/docs` Folder on Master Branch
[As described](https://help.github.com/articles/configuring-a-publishing-source-for-github-pages/#publishing-your-github-pages-site-from-a-docs-folder-on-your-master-branch) in the GitHub Pages docs, you can deploy from a folder called _docs_ on your master branch. This requires to change the Hugo publish directory in your [site configuration[config]; e.g., in `config.toml` and `config.yaml`, respectively:
[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:
```yaml
publishDir: docs
@@ -34,25 +36,29 @@ publishDir: docs
publishDir = "docs"
```
After running `hugo`, push your master branch to the remote repo and choose the _docs_ folder as the website source of your repo (in your GitHub project, go to "Settings " -> "GitHub Pages" -> "Source" -> Select "master branch /docs folder"). If that option isn't enabled, you likely haven't pushed your _docs_ folder yet.
After running `hugo`, push your master branch to the remote repository and choose the `docs/` folder as the website source of your repo. Do the following from within your GitHub project:
This is the simplest approach but requires the usage of a non-standard publish directory (GitHub Pages cannot be configured to use another directory than _docs_ currently). Also the presence of generated files on the master branch may not be to eveyone's taste.
1. Go to **Settings** → **GitHub Pages**
2. From **Source**, select "master branch /docs folder". If the option isn't enabled, you likely do not have a `docs/` folder in the root of your project.
## Deployment via `gh-pages` Branch
{{% note %}}
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 %}}
Alternatively, you can deploy site through a separate branch called "gh_pages". That approach is a bit more complex but has some advantages:
## Deployment From Your `gh-pages` Branch
* It keeps sources and generated HTML in two different branches
* It uses the default _public_ folder
* It keeps the histories of source branch and gh-pages branch fully separated from each other
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:
### Preparations
* 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.
These steps only need to be done once (replace "upstream" with the name of your remote; e.g., `origin`):
### 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
First, add the _public_ folder to _.gitignore_ so it's ignored on the master branch:
First, add the `public` folder to your `.gitignore` file at the project root so that the directory is ignored on the master branch:
```bash
echo "public" >> .gitignore
@@ -60,7 +66,7 @@ echo "public" >> .gitignore
#### Initialize Your `gh-pages` Branch
Then initialize the gh-pages branch as an empty [orphan branch](https://git-scm.com/docs/git-checkout/#git-checkout---orphanltnewbranchgt):
You can now initialize your `gh-pages` branch as an empty [orphan branch][]:
```bash
git checkout --orphan gh-pages
@@ -72,28 +78,38 @@ git checkout master
### Building and Deployment
Now check out the gh-pages branch into your _public_ folder, using git's [worktree feature](https://git-scm.com/docs/git-worktree)
(essentially, it allows you to have multiple branches of the same local repo to be checked out in different directories):
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:
rm -rf public
git worktree add -B gh-pages public upstream/gh-pages
Regenerate the site using Hugo and commit the generated files on the gh-pages branch:
```bash
hugo
cd public && git add --all && git commit -m "Publishing to gh-pages" & cd ..
```sh
rm -rf public
git worktree add -B gh-pages public upstream/gh-pages
```
If the changes in your local gh-pages branch look alright, push them to the remote repo:
Regenerate the site using the `hugo` command and commit the generated files on the `gh-pages` branch:
{{% code file="commit-gh-pages-files.sh"%}}
```bash
hugo
cd public && git add --all && git commit -m "Publishing to gh-pages" && cd ..
```
{{% /code %}}
If the changes in your local `gh-pages` branch look alright, push them to the remote repo:
```bash
git push upstream gh-pages
```
After a short while you'll see the updated contents on your GitHub Pages site.
#### Setting `gh-pages` as Your Publish Branch
### Putting it into a script
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:
1. Go to **Settings** → **GitHub Pages**
2. From **Source**, select "gh-pages branch" and then **Save**. If the option isn't enabled, you likely have not created the branch yet OR you have not pushed the branch from your local machine to the hosted repository on GitHub.
After a short while, you'll see the updated contents on your GitHub Pages site.
### Putting it Into a Script
To automate these steps, you can create a script with the following contents:
@@ -133,9 +149,18 @@ 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
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.
You will also need to set `master` as your publishable branch from within the GitHub UI:
1. Go to **Settings** → **GitHub Pages**
2. From **Source**, select "master branch" and then **Save**.
## Deployment with Git 2.4 and Earlier
The `worktree` command was only introduced in Git 2.5. If you are still on an earlier version and cannot update, you can simply clone your local repo into the _public_ directory, only keeping the gh-pages branch:
The `worktree` command was only introduced in Git 2.5. If you are still on an earlier version and cannot update, you can simply clone your local repository into the _public_ directory, only keeping the gh-pages branch:
```sh
git clone .git --branch gh-pages public
@@ -149,24 +174,31 @@ cd public && git add --all && git commit -m "Publishing to gh-pages" && git push
The other steps are the same as with the worktree approach.
## Hosting Personal or Organization Pages
## Hosting 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.
2. Content from the `master` branch will be used to build and publish your GitHub Pages site.
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 on GitHub `<your-project>-hugo` repository (it will host Hugo's content)
2. Create on GitHub `<username>.github.io` repository (it will host the `public` folder: the static website)
3. `git clone <<your-project>-hugo-url> && cd <your-project>-hugo`
4. Make your website work locally (`hugo server -t <yourtheme>`)
5. Once you are happy with the results, <kbd>Ctrl</kbd>+<kbd>C</kbd> (kill server) and `rm -rf public` (don't worry, it can always be regenerated with `hugo -t <yourtheme>`)
6. `git submodule add -b master git@github.com:<username>/<username>.github.io.git public`
7. Almost done: add a `deploy.sh` script to help you (and make it executable: `chmod +x deploy.sh`):
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.
#### Putting 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:
```sh
#!/bin/bash
@@ -174,12 +206,12 @@ It becomes much simpler in this case: we'll create two separate repos, one for H
echo -e "\033[0;32mDeploying updates to GitHub...\033[0m"
# Build the project.
hugo # if using a theme, replace by `hugo -t <yourtheme>`
hugo # if using a theme, replace with `hugo -t <YOURTHEME>`
# Go To Public folder
cd public
# Add changes to git.
git add -A
git add .
# Commit changes.
msg="rebuilding site `date`"
@@ -191,17 +223,28 @@ git commit -m "$msg"
# Push source and build repos.
git push origin master
# Come Back
# Come Back up to the Project Root
cd ..
```
7. `./deploy.sh "Your optional commit message"` to send changes to `<username>.github.io` (careful, you may also want to commit changes on the `<your-project>-hugo` repo).
That's it! Your personal page is running (after up to 10 minutes delay).
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-PROJECDT>` repository as well.
That's it! Your personal page should be up and running at `https://yourusername.github.io` within a couple minutes.
## Using a Custom Domain
If you'd like to use a custom domain for your GitHub Pages site, create a file _static/CNAME_ with the domain name as its sole contents. This will put the CNAME file to the root of the published site as required by GitHub Pages.
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.
Refer to the [official documentation](https://help.github.com/articles/using-a-custom-domain-with-github-pages/) for further information.
Refer to the [official documentation for custom domains][domains] for further information.
[config]: /getting-started/configuration/
[config]: /getting-started/configuration/
[domains]: https://help.github.com/articles/using-a-custom-domain-with-github-pages/
[ghorgs]: https://help.github.com/articles/user-organization-and-project-pages/#user--organization-pages
[ghpfromdocs]: https://help.github.com/articles/configuring-a-publishing-source-for-github-pages/#publishing-your-github-pages-site-from-a-docs-folder-on-your-master-branch
[ghsignup]: https://github.com/join
[GitHub Pages service]: https://help.github.com/articles/what-is-github-pages/
[orphan branch]: https://git-scm.com/docs/git-checkout/#git-checkout---orphanltnewbranchgt
[Quick Start]: /getting-started/quick-start/
[submodule]: https://github.com/blog/2104-working-with-submodules
[worktree feature]: https://git-scm.com/docs/git-worktree