Blog |

Automated deployment of Hugo generated site to Github pages

Wed, 14 Sep 2016 20:54:16 +0000

In the last post, I listed the typical workflow of generating a static website with Hugo. Here I would like to share the issues I encountered and the tweaks I’ve made. The source codes for this site can be found .

Basic setting in my config.toml for the Academic Theme

Many beautifully designed themes are already . I decided to use the , because it’s specifically designed for academic uses, showcasing publications, personal profile, and projects. For more details, please see the in action.

In config.toml, one can set the universal variables used by Hugo to generate HTML pages. For example:

baseurl = "https://fischcheng.github.io/"
title = "Yu Cheng"
copyright = "&copy; 2016 Yu Cheng"
languageCode = "en-us"
theme = "hugo-academic"

Also some specific parameters used by the chosen theme:

[params.about]
 interests = ["Largescale ocean circulation", "climate variability and modeling"]
 str_interests = "Interests"
 str_education = "Education"

[[params.about.education]]
 course = "BSc in Atmospheric Sciences"
 institution = "National Taiwan University"
 year = 2010

In the academic theme, there are 7 sections on the homepage. The about and teaching sections are under content/home. The content of personal profile is from about.md, yet the entries in interests and education are configured in config.toml.

Three other types of contents are publication, post and project. Each has its unique page layouts, stored under corresponding folders under content. Add a line selected = true in the meta-data part in the publication entry to ensure that entry displayed in the selected publication section.

Next change following items to customize the navigation bar:

[[menu.main]]
 name = "Home"
 url = "#top"
 weight = 1

[[menu.main]]
 name = "Publications"
 url = "#publications"
 weight = 2

[[menu.main]]
 name = "Posts"
 url = "#posts"
 weight = 3

[[menu.main]]
 name = "Research"
 url = "#projects"
 weight = 4

[[menu.main]]
 name = "Works"
 url = "#works"
 weight = 5

[[menu.main]]
 name = "Contact"
 url = "#contact"
 weight = 6

Changing the name will tell Hugo to replace the navbar items and URL for the page that button linked to. I modified the default teaching.md page to works and renamed project section to research. Also, I enabled commenting by setting disqusShortname = "yucheng" in config.toml. And follow this snippet to add a new social network icon:

[[params.social]]
 icon = "envelope" # icon name for email
 icon_pack = "fa" # for font-awesome icons
 link = "mailto:username@xxx.xxx"

On top of the hugo-academic theme, I added an additional stylesheet under static/css. This changes the default color scheme from light blue to green. Besides, I changed the font of the navbar-brand, the title of my site by adding following lines:

.navbar-brand {
 text-transform: uppercase;
 font-weight: bold;
 font-size: 1.5em;
 color: #2b2b2b;
 font-family: 'Permanent Marker', cursive;
}

The contents within static/js and static/ccs will be included in the header.html after the default ccs stylesheets, so it’s totally possible to change color scheme without modifying anything in the themes/academic. However, to change fonts, I modified themes/academic/layouts/partials/header.html to load an additional font Permanent Marker from google fonts.

<link rel="stylesheet" href="//fonts.googleapis.com/css?family=Lato:400,700|Merriweather|Roboto+Mono|Permanent+Marker">

Github pages, user site or project site

Two kinds of site are supported on GitHub pages, the user/organization site, and the project site. For the former, the site itself is a repository, everything under master branch will be displayed under this address https://<username>.github.io, which is customizable. And the later is a website to showcase an existed repo. Without changing the original branch, everything under gh-pages branch can be accessed under http://<username>.github.io/<repository>. Github even provides an Automatic Generator to help to create a project site. More details can be found .

My website is an user site. Under this repo fischcheng.github.io, the source branch archived all changes to the source codes, and master branch store the Hugo-generated HTML pages.

Automated deployment using Wercker

The default way to build a hugo site is simple, invoke hugo under the site root. A public folder will be created, containing every HTML pages and copied stylesheets and static files (banner images and profile icons or so). Push this folder to the master branch, and voila, the site is online.

What if a single push to the source branch (or whatever name of your development branch) can trigger all the rest steps? Travis-CI was my old choice for the last version of this site, until I came across this wonderful guide on Hugo’s official . However, things changed a lot since that article was last edited and below I would like to detail all the issues I ran into and how I solved them.

is a continuous integration (CI) tool that helps developers to build, test and deploy their applications based on . A Wercker account can be easily hooked to a given Github or Bitbucket account, and one can create new applications from a chosen repository. After setting up, a push to the repository will automatically trigger the application. One of the biggest advantages of Wercker over Travis-CI is the collection of easily-located and well-documented steps. In our case, the application consists of two steps build hugo and deploy to GitHub.

Wercker dashboard: to find existed steps, click the Registry tab; to create your own applications and steps, access the Create tab.

The first task is to create the config.yml ( ) in the developing branch. Please follow the original Hugo guide to setup the link between a Wercker application to the Github. Below, I will only list out the discrepancies I encountered.

Build

Following the official guide, I used this to trigger Hugo to build HTML pages. However, my first try didn’t successfully generate the pages correctly, because the arjen/hugo-build step couldn’t find the hugo-academic theme. For easier tracking and updating, I forked the hugo-academic repo, and I later realized that, for a repo embedded within another repo, the former is counted as a submodule. For the build step to work as desired, I had to install git and initialize submodule to ensure that the build step can locate the hugo-academic theme. Kudos to this which helped me to track this issue down.

box: debian

build:
 steps:
 - script:
 name: install git
 code: |
 apt-get update
 apt-get install git -y
 - script:
 name: initialize git submodules
 code: |
 git submodule update --init --recursive
 - arjen/hugo-build@1.11.0:
 version: "0.15"
 theme: "hugo-academic"
 flags: --buildDrafts=true

Deploy

There is no more such thing as “Add deploy target” in Wercker. The interface has changed to the new “workflows of pipelines.” This change is so new that even the documentation on Wercker website has not changed yet. Their customer service still referred me to the old supporting materials.

So I poked around and realized that, even if the second deploy step is included in the wercker.yml, one still needs to manually add a new “pipeline” under the “workflow” tab. Upon creating a new pipeline, the “YML pipeline name” must be in the predefined names in the wercker.yml.

Here I used this to deploy the built site to GitHub. Each pipeline starts from scratch. So for the deploy pipeline, the git package needs to be installed again. One also has to setup the environment variable $Git_Token, acquired from Github setting.

deploy:
 steps:
 - script:
 name: install git
 code: |
 apt-get update && apt-get install git -y
 - leipert/git-push@0.7.6:
 gh_oauth: $Git_Token
 gh_pages: true
 basedir: public
 branch: master

Click deploy pipeline to setup included environment variables. Get the Github access token from Github profile setting.

Switch from Pelican to Hugo

Wed, 14 Sep 2016 01:16:30 +0000

Being a big fan of all things Python, I built the last two incarnations of this site with Pelican. I even went to the length to set up a Travis CI to automatically build and deploy to GitHub pages. That was the beginning of the summer and only two new posts ever since.

Recently, my boss has brought up the topic of building a group website. Also, there is a joint-project website needs to be done. Most other groups in the school have their group website, mostly hosted by Weebly, Wordpress or Wix. Those website services certainly have pros. For one, a Weebly site can easily allow multiple contributors. But most customization and advanced features are usually not free.

So, I shared my experience of hosting a static site on Github pages and showed off my Pelican-powered website. By generating your own website, hosted by some popular cloud services (i.e. Amazon S3 and Github), one has full control to the contents and styles. All other responsive features such as site analytics and commenting can be achieved by integrating with existed online services.

Static site generators

Options are plenty, to name a few, Jekyll, Octopress, Pelican, Middleman, and Hugo. They were written in different languages (Ruby, JavaScript, Python and Go, etc.) but serve the same goal – construct the bare bone of a website and render the contents to the publishable HTML pages.

Not every site generators were created equal. Folks from different languages tend to choose the one they are familiar with. That was why I used Pelican initially. For the time-being, I realized that Pelican community is not very active, and theme options seems a bit thin. Jekyll is more matured, and there are already numerous professional-like themes available. However, it is Hugo that caught my eyes.

Hugo has certainly attracted many people from Jekyll. The binary itself is written in Go, and no other dependencies are necessary. It renders Markdown file to HTML really fast (we are talking about millisecond here.) Its structure makes switching between themes and customization overwriting the chosen theme super easy. Also, Hugo was the name I had during the 7-day intensive Spanish program that I completed in the past summer.

hugo

Hugo workflow

Let me walk you through the basics of building a Hugo-powered website. For more details, readers are referred to the official Hugo

Install Hugo binary: for OS X (and the future Mac OS) users, it’s recommended to do it through homebrew, just like for most open-source software.
```
 brew install hugo
```
Create a new site under the desired root directory:
```
 hugo new site sitename
```

The generated directory have the following layout:

 .
|-- archetypes
|-- config.toml
|-- content
|-- data
|-- layouts
`-- static
5 directories, 1 file

Create new posts under the content folder:
```
 hugo new post/postname.md
```
config.toml is the key configuration file to let Hugo know how to render the contents.
Pick a theme from or build your own. To apply a theme, one needs to create a themes folder under the root, and git clone or make a new-theme directory under this folder. Then switching themes can be achieved by adding a line in config.toml file like this theme = "hugo-academic", or tell hugo which theme to build with using this command hugo server --theme=hugo_theme_name
Check the results by running a virtual server, which automatically listens to any changes you make and render HTML in real time. Go to to see your shiny new site in action.
```
 hugo server --watch
```
Build the pages by invoking hugo. Generated HTML pages will by default be stored under public folder. It is this folder you need to find a home to host.

comments and tips

Posts are usually written in Markdown, though it also supports other markup languages. Markdown is really elegant and easy to use, definitely worth picking up.
The equivalent of extension in Hugo is shortcodes, which are stored under layout/shortcodes directory. These pre-defined snippets can allow site-owner to embed Youtube, Vimeo players and individual tweet into their posts.
Most themes support Disqus for commenting or google-analytic for analyzing website usage.
The format of metadata in the markdown files might be different from those using other site-generators. So, migrating old posts to Hugo needs some works (could be easily down with some simple parsing scripts.)
Add customized CSS stylesheet under static to overwrite settings in the chosen theme.