"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "docs/content/en/hosting-and-deployment/hosting-on-github.md" between
hugo-0.80.0.tar.gz and hugo-0.81.0.tar.gz

About: Hugo is a static site generator that takes a source directory of Markdown files and templates and uses these as input to create a complete website (written in Go).

hosting-on-github.md  (hugo-0.80.0):hosting-on-github.md  (hugo-0.81.0)
--- ---
title: Host on GitHub title: Host on GitHub
linktitle: Host on GitHub linktitle: Host on GitHub
description: Deploy Hugo as a GitHub Pages project or personal/organizational si te and automate the whole process with a simple shell script. description: Deploy Hugo as a GitHub Pages project or personal/organizational si te and automate the whole process with Github Action Workflow
date: 2014-03-21 date: 2014-03-21
publishdate: 2014-03-21 publishdate: 2014-03-21
lastmod: 2018-09-22
categories: [hosting and deployment] categories: [hosting and deployment]
keywords: [github,git,deployment,hosting] keywords: [github,git,deployment,hosting]
authors: [Spencer Lyon, Gunnar Morling] authors: [Spencer Lyon, Gunnar Morling]
menu: menu:
docs: docs:
parent: "hosting-and-deployment" parent: "hosting-and-deployment"
weight: 30 weight: 30
weight: 30 weight: 30
sections_weight: 30 sections_weight: 30
draft: false
toc: true toc: true
aliases: [/tutorials/github-pages-blog/] 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 servi ce][]. GitHub provides free and fast static hosting over SSL for personal, organization , or project pages directly from a GitHub repository via its [GitHub Pages servi ce][] and automate development workflows and build with [GitHub Actions].
## Assumptions ## Assumptions
1. You have Git 2.8 or greater [installed on your machine][installgit]. 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. 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 [Quic k Start][]. 3. You have a ready-to-publish Hugo website or have at least completed the [Quic k Start][].
## Types of GitHub Pages ## Types of GitHub Pages
There are 2 types of GitHub Pages: There are two types of GitHub Pages:
- User/Organization Pages (`https://<USERNAME|ORGANIZATION>.github.io/`) - User/Organization Pages (`https://<USERNAME|ORGANIZATION>.github.io/`)
- Project Pages (`https://<USERNAME|ORGANIZATION>.github.io/<PROJECT>/`) - 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 t o use. 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 t o use.
To create a User/Organization Pages site, follow the single method in the *GitHu
b 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 ## GitHub User or Organization Pages
As mentioned in the [GitHub Pages documentation][ghorgs], you can host a user/or ganization page in addition to project pages. Here are the key differences in Gi tHub Pages websites for Users and Organizations: As mentioned in the [GitHub Pages documentation][ghorgs], you can host a user/or ganization page in addition to project pages. Here are the key differences in Gi tHub Pages websites for Users and Organizations:
1. You must use a `<USERNAME>.github.io` to host your **generated** content 1. You must use a `<USERNAME>.github.io` to host your **generated** content
2. Content from the `main` branch will be used to publish your GitHub Pages site 2. Content from the `main` branch will be used to publish your GitHub Pages site
This is a much simpler setup as your Hugo files and generated content are publis hed into two different repositories. This is a much simpler setup as your Hugo files and generated content are publis hed into two different repositories.
### Step-by-step Instructions ## Build Hugo With GitHub Action
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 tha
t will contain the fully rendered version of your Hugo website.
3. `git clone <YOUR-PROJECT-URL> && cd <YOUR-PROJECT>`
4. Paste your existing Hugo project into the new local `<YOUR-PROJECT>` reposito
ry. Make sure your website works locally (`hugo server` or `hugo server -t <YOUR
THEME>`) 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
* Before proceeding run `rm -rf public` to completely remove the `public` di
rectory
6. `git submodule add -b main https://github.com/<USERNAME>/<USERNAME>.github.io
.git public`. This creates a git [submodule][]. Now when you run the `hugo` comm
and to build your site to `public`, the created `public` directory will have a d
ifferent remote origin (i.e. hosted GitHub repository).
7. Make sure the `baseURL` in your config file is updated with: `<USERNAME>.gith
ub.io`
### Put it Into a Script
You're almost done. In order to automate next steps create a `deploy.sh` script.
You can also make it executable with `chmod +x deploy.sh`.
The following are the contents of the `deploy.sh` script:
```
#!/bin/sh
# If a command fails then the deploy stops
set -e
printf "\033[0;32mDeploying updates to GitHub...\033[0m\n"
# 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 [ -n "$*" ]; then
msg="$*"
fi
git commit -m "$msg"
# Push source and build repos.
git push origin main
```
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 you
r `<YOUR-PROJECT>` repository as well.
That's it! Your personal page should be up and running at `https://<USERNAME>.gi
thub.io` within a couple minutes.
## GitHub Project Pages GitHub execute your software development workflows. Everytime you push your code on the Github repository, Github Action will build the site automatically.
{{% note %}} Create a file in `.github/workflows/gh-pages.yml` containing the following conte
Make sure your `baseURL` key-value in your [site configuration](/getting-started nt (based on https://github.com/marketplace/actions/hugo-setup ):
/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 no
t a custom domain.
{{% /note %}}
### Deployment of Project Pages from `/docs` folder on `main` branch ```yml
name: github pages
[As described in the GitHub Pages documentation][ghpfromdocs], you can deploy fr on:
om a folder called `docs/` on your main branch. To effectively use this feature push:
with Hugo, you need to change the Hugo publish directory in your [site's][config branches:
] `config.toml` and `config.yaml`, respectively: - main # Set a branch to deploy
``` jobs:
publishDir = "docs" deploy:
``` runs-on: ubuntu-18.04
``` steps:
publishDir: docs - uses: actions/checkout@v2
``` with:
submodules: true # Fetch Hugo themes (true OR recursive)
After running `hugo`, push your main branch to the remote repository and choose fetch-depth: 0 # Fetch all history for .GitInfo and .Lastmod
the `docs/` folder as the website source of your repo. Do the following from wit
hin your GitHub project: - name: Setup Hugo
uses: peaceiris/actions-hugo@v2
1. Go to **Settings** &rarr; **GitHub Pages** with:
2. From **Source**, select "main branch /docs folder". If the option isn't enab hugo-version: 'latest'
led, you likely do not have a `docs/` folder in the root of your project. # extended: true
{{% note %}} - name: Build
The `docs/` option is the simplest approach but requires you set a publish direc run: hugo --minify
tory in your site configuration. You cannot currently configure GitHub pages to
publish from another directory on main, and not everyone prefers the output site - name: Deploy
live concomitantly with source files in version control. uses: peaceiris/actions-gh-pages@v3
{{% /note %}} with:
github_token: ${{ secrets.GITHUB_TOKEN }}
### Deployment of Project Pages From Your `gh-pages` branch publish_dir: ./public
You can also tell GitHub pages to treat your `main` branch as the published site
or point to a separate `gh-pages` branch. The latter approach is a bit more com
plex 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 main branch:
```
echo "public" >> .gitignore
``` ```
##### Initialize Your `gh-pages` Branch For more advance settings https://github.com/marketplace/actions/hugo-setup
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 main
```
#### Build and Deployment
Now check out the `gh-pages` branch into your `public` folder using git's [workt
ree feature][]. Essentially, the worktree allows you to have multiple branches o
f 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 t
he `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 re
mote 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 automati
cally once GitHub realizes you've created this branch. You can also set the bran
ch manually from within your GitHub project:
1. Go to **Settings** &rarr; **GitHub Pages**
2. From **Source**, select "gh-pages branch" and then **Save**. If the option i
sn'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
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)
"
#echo "Pushing to github"
#git push --all
{{< /code >}}
This will abort if there are pending changes in the working directory and also m
akes sure that all previously existing output files are removed. Adjust the scri
pt 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.
### Deployment of Project Pages from Your `main` Branch
To use `main` as your publishing branch, you'll need your rendered website to li
ve 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 repositor
y with the `public` directory as the root. Note that this does not provide the s
ame benefits of the `gh-pages` branch in keeping your source and output in separ
ate, but version controlled, branches within the same repo.
You will also need to set `main` as your publishable branch from within the GitH
ub UI:
1. Go to **Settings** &rarr; **GitHub Pages**
2. From **Source**, select "main branch" and then **Save**.
## Use a Custom Domain ## 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. 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 requirement of GitHub Pages.
Refer to the [official documentation for custom domains][domains] for further in formation. Refer to the [official documentation for custom domains][domains] for further in formation.
[config]: /getting-started/configuration/ [config]: /getting-started/configuration/
[domains]: https://help.github.com/articles/using-a-custom-domain-with-github-pa ges/ [domains]: https://help.github.com/articles/using-a-custom-domain-with-github-pa ges/
[ghorgs]: https://help.github.com/articles/user-organization-and-project-pages/# user--organization-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/ [ghpfromdocs]: https://help.github.com/articles/configuring-a-publishing-source- for-github-pages/
[ghsignup]: https://github.com/join [ghsignup]: https://github.com/join
[GitHub Pages service]: https://help.github.com/articles/what-is-github-pages/ [GitHub Pages service]: https://help.github.com/articles/what-is-github-pages/
[installgit]: https://git-scm.com/downloads [installgit]: https://git-scm.com/downloads
[orphan branch]: https://git-scm.com/docs/git-checkout/#Documentation/git-checko ut.txt---orphanltnewbranchgt [orphan branch]: https://git-scm.com/docs/git-checkout/#Documentation/git-checko ut.txt---orphanltnewbranchgt
[Quick Start]: /getting-started/quick-start/ [Quick Start]: /getting-started/quick-start/
[submodule]: https://github.com/blog/2104-working-with-submodules [submodule]: https://github.com/blog/2104-working-with-submodules
[worktree feature]: https://git-scm.com/docs/git-worktree [worktree feature]: https://git-scm.com/docs/git-worktree
[GitHub Actions]: https://docs.github.com/en/actions
 End of changes. 14 change blocks. 
238 lines changed or deleted 39 lines changed or added

Home  |  About  |  Features  |  All  |  Newest  |  Dox  |  Diffs  |  RSS Feeds  |  Screenshots  |  Comments  |  Imprint  |  Privacy  |  HTTP(S)