How to create a website like freshswift.net using Hugo, Travis CI, and GitHub Pages

July 15, 2017
hugo github travis swift

I recently launched freshswift.net, a site of regularly updated, curated Swift links. I built it using Hugo, Travis CI, and GitHub Pages.

My goal in creating freshswift.net was to create a site which I could easily update with new posts at any time from any device.

In this post I describe;

  • The tools & services you need to create such a site

  • The steps required to get a site up and running

  • How you can easily update your site with new content

Note: This post assumes that you are using a Mac, have basic knowledge of GitHub and continuous integration tools such as Travis CI (i.e you know what they are), and have experience using terminal on a Mac.


Tools and Services

Hugo

Hugo is an open source static website generator. What this means is that it builds (generates HTML) a website for you based on content and formatting you specify.

Travis CI

Travis CI is a hosted continuous integration service which is used to build & distribute projects. Projects hosted on GitHub can be automatically built when they have been updated/changed.

Github Pages

GitHub Pages is a service from GitHub which allows you to host a website for your GitHub profile or any GitHub project repository.


Getting up and running

1. Create a GitHub repository to host your site

Create a (free) GitHub account here if you don’t already have one. Now create a new public repository. This respository will host both the files you use to generate your site using Hugo, and the files generated by Hugo which will be your site’s files (Woah!).

2. Install Hugo

Install Hugo based on this.

3. Create a basic site using Hugo

Following this guide, create a basic site (and optionally add a theme you like).

4. Push your Hugo files to your GitHub repository

Using this guide, push your Hugo content to your GitHub repository.

5. Create a GitHub Personal Access Token

As described in step 8 below, you need to provide Travis with a Personal Access Token. You can generate this token in your GitHub account settings. When you generate it, make sure the repo checkbox is ticked. This will give Travis the permissions it needs to push to your repository (again, more on this is in step 8 below).

6. Create a Travis CI account

Starting here, create a Travis account by signing in to Travis with your GitHub account. When you create your Travis account, you grant Travis access to your GitHub account, which means Travis can access your GitHub repositories.

Travis is free for open source projects. The GitHub repository you created earlier to host your site is public, i.e your site is open source!

7. Configure Travis CI to generate your site

On your Travis profile page, you need to set Travis to build your Hugo GitHub repository.

In your case, this build will generate your site for you. Travis build configuration is done via a .travis.yml file. More information than you need right now can be found here. Basically, you need to add a .travis.yml file to your GitHub repository. You then add the information Travis needs to build your site.

Below are the relevant lines from the freshswift.net .travis.yml file, which you can use to specify how to build your Hugo site;

# Install the apt prerequisites
addons:
  apt:
    packages:
      - python-pygments
# Clean and don't fail
install:
  - rm -rf public || exit 0
# Build the website
script:
  - binaries/hugo --theme=fresh

8. Configure Travis CI to push your generated site to GitHub

Travis needs write-access to your GitHub repository. You provide this write access via a Travis environment variable which uses the the GitHub Personal Access Token you generated previously in step 5. Environment variables can be specified in the Travis repository setting. For yourPersonal Access Token, you create an environment variable named GITHUB_TOKEN.

After Travis generates your site, you want to push the generated files to GitHub. Again, you configure this in the .travis.yml file, adding the following lines;

# Deploy to GitHub pages
deploy:
  provider: pages
  skip_cleanup: true
  github_token: $GITHUB_TOKEN
  local_dir: public
  on:
    branch: master

What this actually does is;

  • Specify that you want to host your site on GitHub pages

  • Skip cleanup after a build you don’t want to delete the Hugo files you use to generate your site

  • Tell Travis to use your GitHub Personal Access Token environment variable

  • Indicate that you want your generated site to be placed in a public directory

  • Tell Travis to build the GitHub master branch

When Travis builds a GitHub pages project like yours, it automatically pushes the generated files to a branch named gh-pages. If this branch does not yet exist, it creates it and pushes the generated files to the branch.

9. Configure GitHub pages for your site repository

Now that you have your generated site files on a gh-pages branch in your GitHub repository, you need to configure GitHub pages to use this branch as the source of your site. You configure this in the Settings tab in your GitHub repository. In the Settings tab, find the GitHub Pages section, and select ‘gh-pages branch’ from the Source drop menu. 

Note this option will only be available if this branch already exists. The branch will exist if step 8 completed successfully (when Travis pushes the generated site to the gh-pages branch for the first time, the gh-pages branch will be created).

🎉 That should be it! Your site should now be up and running at https://ourUserName.github.io/ourProjectName.

* Optional - Setting up a custom domain name

In addition to using the GitHub pages address for your site, you can optionally use a custom domain name, such as freshswift.net. The steps here outline how you can do this. However, as your site is generated by Travis whenever you make a change, you need to do something a little special for the ‘Setting up a www subdomain’ step. As part of the travis build, you need to create the cname file, so it can be pushed to your gh-pages branch whenever your site is generated. You accomplish this by adding the following line to your .travis.yml file, right after the Hugo build step;

# Build the website
script:
  - binaries/hugo --theme=fresh
  # Create a CNAME file which maps your site to your custom domain
  - echo 'freshswift.net' > public/CNAME

Above you can see how the freshswift.net cname file is generated as part of the Travis build.


Updating your site with new content

Hugo works by generating your site from content you specify in markdown files. Normally when you add new content, e.g a new blog post in a new markdown file, you need to manually re-generate the site using Hugo, and publish it.  However…and this is the cool part…in your case all you need to do is create the markdown file and push it to your GitHub repository master branch. No need for you to re-generate your site manually using Hugo and push the generated site to GitHub,Travis takes care of this for you. Automation FTW! Also, as GitHub allows you to to create and edit new files via it’s web interface, you can pretty much add new markdown (new site content) from any device.


More information

  • freshswift.net is hosted publicly on GitHub, and so all files/code can be found here

  • For freshswift.net I actually created a simple iOS app which enables me to quickly create and push a new markdown file to GitHub, but it’s not something that’s required to gain the benefits of the approach described in this post


That’s it! 📱🚀👍🏽