PART 3: Hugo: Installation, Setup and publishing to GitHub pages using a custom domain.

Learn how to install and set-up Hugo, and publish to GitHub pages using a custom domain.

Root

6 minute read

Introduction

This is Part 3 of my journey installing hugo, setting up Hugo on my authoring machines and publishing the site to GitHub pages using a custom domain.

I will detail both Windows 10 and Ubuntu-19.10 setups.

Click here for Part 1.

In Part 1

  1. Installing Hugo
  2. Configuring Hugo
  3. Creating a Hugo Site

Click here for Part 2.

In Part 2

  1. Installing Git
  2. Setting up GitHub
  3. Setting up Git to work with Hugo
  4. Installing a Theme
  5. Running the site for the first time
  6. Pushing all the code to GitHub

Click here for Part 3.

In Part 3

  1. Build the site for the first time
  2. Adding the published site to GitHub
  3. Ongoing editing and publishing

windows

Build the site first time

Before we build our site for the first time we are going to make a small change to the config.toml file to build the site into docs instead of the traditional public sub-folder. This is to allow us to work with GitHub’s Pages hosting service that expects a docs folder.

REM Add the following line to config.toml

publishDir = "docs"

REM Save the config.toml file

We are now ready to build the site.

REM Build the site for the first time by running just hugo by itself
C:\Hufo\Sites\PasswdTest.Blog>hugo

Building sites …
                   | EN
+------------------+----+
  Pages            | 32
  Paginator pages  |  2
  Non-page files   |  0
  Static files     | 17
  Processed images |  0
  Aliases          |  6
  Sitemaps         |  1
  Cleaned          |  0

Total in 139 ms

You should now see a docs folder in C:\Hugo\Sites\PasswdTest.Blog

This folder contains the compiled site that can be hosted on various platforms, we are going to us GitHub Pages to host our site.

Adding the published site to GitHub

REM Add the new files to git
C:\Hugo\Sites\PasswdTest.Blog> git add .


C:\Hugo\Sites\PasswdTest.Blog> git commit -m "Initial Docs Commit"

C:\Hugo\Sites\PasswdTest.Blog> git push --force origin master

REM The --force above is a bit of a work-around because (I think) GitHub add the CNAME file to the docs folder which causes Git to throw and error indicating that files have changed on the server and a pull needs to be done first before pushing. I haven't had time to investigate a more elegant solution. Because I am the only author at this stage --force doesn't cause any issues for me.

Refresh your GitHub repository, you should now have a docs folder.

Click on Settings in the repository view of GitHub. Scroll down to GitHub Pages and click on None under Source.

Select master brance /docs folder. The page will refresh, scroll down again and enter your custom domain name in the field, check Enforce HTTPS and click save.

You will now be able to browse to your domain and see the sample tempate site.

Ongoing editing and publishing

Browse to the docs folder in your GitHub repository. You will see a CNAME file that was generated by GitHub when you saved you domain name in the previous section.

The recomendation from Hugo is to delete the public or docs folder before every build, otherwise any deleted files will remain on the published site.

When deteting the docs folder the generated CNAME file will also be deleted and you will have to enter the domain name again.

To streamline the process we are going to create the CNAME file using a deply script.

The deploy-passwdtemp.blog.bat file below will allow you to automate the deployment process.

Place the batch file in the C:\Hugo\Sites directory!!

@ECHO OFF

ECHO "STEP 1 - Removing the previous docs folder"
rd /S /Q C:\Hugo\Sites\PasswdTest.Blog\docs

C:
cd Hugo\Sites\PasswdTest.Blog


ECHO "STEP 2 - Building the site with hugo"
hugo


ECHO "STEP 3 - Add the CNAME file"
ECHO Passwd.Blog > C:\Hugo\Sites\PasswdBlog\CNAME


ECHO "STEP 4 - Setting Git Parameters"
git config user.name "your_github_username"
git config user.email "your_github_email@domain.com"

ECHO "STEP 5 - Git add ."
git add .


ECHO "STEP 6 - git commit (Use the current date and time in the commit comment)"
set backupFilename="rebuilding site %DATE:~10,4%-%DATE:~4,2%-%DATE:~7,2% @ %time:~0,2%:%time:~3,2%:%time:~6,2%"
git commit -m %backupFilename%


ECHO "STEP 7 - git push"
git push --force origin master

cd ..

Once you have completed editing your site content, just run deploy-passwdtemp.blog.bat from C:\Hugo\Sites


ubuntu

Build the site first time

Before we build our site for the first time we are going to make a small change to the config.toml file to build the site into docs instead of the traditional public sub-folder. This is to allow us to work with GitHub’s Pages hosting service that expects a docs folder.

# Add the following line to config.toml

publishDir = "docs"

# Save the config.toml file

We are now ready to build the site.

R# Build the site for the first time by running just hugo by itself
~/Sites/PasswdTest.Blog$ hugo

Building sites …
                   | EN
+------------------+----+
  Pages            | 32
  Paginator pages  |  2
  Non-page files   |  0
  Static files     | 17
  Processed images |  0
  Aliases          |  6
  Sitemaps         |  1
  Cleaned          |  0

Total in 139 ms

Adding the published site to GitHub

# Add the new files to git
~/Sites/PasswdTest.Blog$ git add .


~/Sites/PasswdTest.Blog$ git commit -m "Initial Docs Commit"

~/Sites/PasswdTest.Blog$ git push --force origin master

# The --force above is a bit of a work-around because (I think) GitHub add the CNAME file to the docs folder which causes Git to throw and error indicating that files have changed on the server and a pull needs to be done first before pushing. I haven't had time to investigate a more elegant solution. Because I am the only author at this stage --force doesn't cause any issues for me.

Refresh your GitHub repository, you should now have a docs folder.

Click on Settings in the repository view of GitHub. Scroll down to GitHub Pages and click on None under Source.

Select master brance /docs folder. The page will refresh, scroll down again and enter your custom domain name in the field, check Enforce HTTPS and click save.

You will now be able to browse to your domain and see the sample tempate site.

Ongoing editing and publishing

Browse to the docs folder in your GitHub repository. You will see a CNAME file that was generated by GitHub when you saved you domain name in the previous section.

The recomendation from Hugo is to delete the public or docs folder before every build, otherwise any deleted files will remain on the published site.

When deteting the docs folder the generated CNAME file will also be deleted and you will have to enter the domain name again.

To streamline the process we are going to create the CNAME file using a deply script.

The deploy-passwdtemp.blog.sh file below will allow you to automate the deployment process.

Place the bash script in the ~/Sites directory!!

#!/bin/sh

printf "STEP 1 - Removing the previous docs folder"
rd /S /Q C:\Hugo\Sites\PasswdTest.Blog\docs


cd ~/Sites\PasswdTest.Blog


printf "STEP 2 - Building the site with hugo"
hugo


printf "STEP 3 - Add the CNAME file"
echo Passwd.Blog > C:\Hugo\Sites\PasswdBlog\CNAME


printf "STEP 4 - Setting Git Parameters"
git config user.name "your_github_username"
git config user.email "your_github_email@domain.com"

printf "STEP 5 - Git add ."
git add .


printf "STEP 6 - git commit (Use the current date and time in the commit comment)"
msg="rebuilding site $(date)"
git commit -m "$msg"


printf "STEP 7 - git push"
git push --force origin master

cd ..

Once you have completed editing your site content, just run deploy-passwdtemp.blog.sh from ~/Sites

Remember to sudo chmod 777 deploy-passwdtemp.blog.sh to make it executable.

comments powered by Disqus