mirror of
https://github.com/gohugoio/hugo.git
synced 2024-11-14 20:37:55 -05:00
83bef6955e
e161ea09d Add one more Chinese file to workaround reflect: Zero(nil) b595b3a21 Add more Chinese translation 56e4e95d9 Use lang.Merge to "fill in the gaps" for untranslated pages ef079406c Merge commit '650fac3a4e7d256f4505402ab44cfc3c804b8dea' 650fac3a4 Squashed 'themes/gohugoioTheme/' changes from a1768ebb..f31a3dc8 322eff899 Add Chinese language for menus d90b886e0 Fix Markdown table syntax in previous commit 737f3dfca Update the leaf bundle vs branch bundle table 09fa1bc4e Clarify that `.Now` is obsolete 879ea3f6a Make release notes somewhat more consistent 0113e2051 Move 0.40.2-relnotes into content/en/news 77578f5bf Move content/ into new contentDir content/en/ 4dcf7c709 Fix "reflect: Zero(nil)" error in showcase 63dd25505 Release 0.40.2 2076c0d56 releaser: Prepare repository for 0.41-DEV 070fe565e releaser: Add release notes to /docs for release of 0.40.2 4ce52e913 releaser: Bump versions for release of 0.40.2 41907c487 Fix typos in syntax-highlighting.md 91753ef3d Add missing backtick b77274301 Remove duplicate release notes (0.27, 0.27.1, 0.35) 6e00da316 Remove obsolete content/release-notes/ directory 00a6d8c02 Change en dash back to `--` in 0.38.2-relnotes 51b32dc00 Update archetypes.md d0e5c2307 Release 0.40.1 4538a6d5b releaser: Prepare repository for 0.41-DEV 91b391d70 releaser: Add release notes to /docs for release of 0.40.1 e0979d143 releaser: Bump versions for release of 0.40.1 7983967c2 Clean images fe3fdd77d Polish showcase for Flesland Flis e6dde3989 Showcase - Flesland Flis AS by Absoluttweb 73aa62290 Revive @spf13's special Hugo font add67b335 Release Hugo 0.40 c0a26e5a6 Merge branch 'temp40' beeabaaae releaser: Prepare repository for 0.41-DEV e67d5e985 releaser: Add release notes to /docs for release of 0.40 6cdd95273 releaser: Bump versions for release of 0.40 bee21fb9b Revive the other Hugo logos too 4f45e8fe1 Fix the link type attribute for RSS in examples 8c67dc89a Fix example in delimit doc e7f6c00d5 Revive the logo used on the forum 82b0cd26e Merge commit 'a215abf70e018f4bf40d6c09d8bd148d8684b33d' 119c8ca58 Merge commit 'd2ec1a06df8ab6b17ad05cb008d5701b40327d47' db4683bd2 Improve .Get docs 05260b886 .Get function: fix syntax signature git-subtree-dir: docs git-subtree-split: e161ea09d33e3199f4998e4d2e9068d5a850f042
252 lines
11 KiB
Markdown
252 lines
11 KiB
Markdown
---
|
|
title: Host on GitHub
|
|
linktitle: Host on GitHub
|
|
description: Deploy Hugo as a GitHub Pages project or personal/organizational site and automate the whole process with a simple shell script.
|
|
date: 2014-03-21
|
|
publishdate: 2014-03-21
|
|
lastmod: 2017-03-30
|
|
categories: [hosting and deployment]
|
|
keywords: [github,git,deployment,hosting]
|
|
authors: [Spencer Lyon, Gunnar Morling]
|
|
menu:
|
|
docs:
|
|
parent: "hosting-and-deployment"
|
|
weight: 30
|
|
weight: 30
|
|
sections_weight: 30
|
|
draft: false
|
|
toc: true
|
|
aliases: [/tutorials/github-pages-blog/]
|
|
---
|
|
|
|
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
|
|
|
|
1. You have Git 2.8 or greater [installed on your machine][installgit].
|
|
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][].
|
|
|
|
## 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/<PROJECT>/`) and not a custom domain.
|
|
{{% /note %}}
|
|
|
|
### 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:
|
|
|
|
```
|
|
publishDir = "docs"
|
|
```
|
|
```
|
|
publishDir: docs
|
|
```
|
|
|
|
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:
|
|
|
|
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.
|
|
|
|
{{% 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 %}}
|
|
|
|
### 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
|
|
|
|
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 your `.gitignore` file at the project root so that the directory is ignored on the master branch:
|
|
|
|
```
|
|
echo "public" >> .gitignore
|
|
```
|
|
|
|
##### Initialize Your `gh-pages` Branch
|
|
|
|
You can now initialize your `gh-pages` branch as an empty [orphan branch][]:
|
|
|
|
```
|
|
git checkout --orphan gh-pages
|
|
git reset --hard
|
|
git commit --allow-empty -m "Initializing gh-pages branch"
|
|
git push upstream gh-pages
|
|
git checkout master
|
|
```
|
|
|
|
#### 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:
|
|
|
|
```
|
|
rm -rf public
|
|
git worktree add -B gh-pages public upstream/gh-pages
|
|
```
|
|
|
|
Regenerate the site using the `hugo` command and commit the generated files on the `gh-pages` branch:
|
|
|
|
{{< code file="commit-gh-pages-files.sh">}}
|
|
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:
|
|
|
|
```
|
|
git push upstream gh-pages
|
|
```
|
|
|
|
##### 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:
|
|
|
|
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.
|
|
|
|
#### Put it Into a Script
|
|
|
|
To automate these steps, you can create a script with the following contents:
|
|
|
|
{{< code file="publish_to_ghpages.sh" >}}
|
|
#!/bin/sh
|
|
|
|
DIR=$(dirname "$0")
|
|
|
|
cd $DIR/..
|
|
|
|
if [[ $(git status -s) ]]
|
|
then
|
|
echo "The working directory is dirty. Please commit any pending changes."
|
|
exit 1;
|
|
fi
|
|
|
|
echo "Deleting old publication"
|
|
rm -rf public
|
|
mkdir public
|
|
git worktree prune
|
|
rm -rf .git/worktrees/public/
|
|
|
|
echo "Checking out gh-pages branch into public"
|
|
git worktree add -B gh-pages public upstream/gh-pages
|
|
|
|
echo "Removing existing files"
|
|
rm -rf public/*
|
|
|
|
echo "Generating site"
|
|
hugo
|
|
|
|
echo "Updating gh-pages branch"
|
|
cd public && git add --all && git commit -m "Publishing to gh-pages (publish.sh)"
|
|
{{< /code >}}
|
|
|
|
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 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.
|
|
|
|
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**.
|
|
|
|
## 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.
|
|
|
|
Refer to the [official documentation for custom domains][domains] for further information.
|
|
|
|
[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/
|
|
[installgit]: https://git-scm.com/downloads
|
|
[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
|