Revitalizing my Blog with Hugo and GitHub Actions (aka a New Hope)

This is my third attempt to revitalize my blog since 2008. I never migrated my old posts. Some of the posts were referenced externally which I did not expect. Some of them were also posted as links in Stack Overflow answers. I realized that when I got some messages from Twitter why my post disappeared. Luckily this is not a problem anymore, because all of the topics are outdated and nobody cares anymore. 😌

First I started with WordPress. This was quite easy and straightforward. One big problem was that I did not care about the updates. Yes, I have self-hosted WordPress. In hindsight it was a really bad decision. After some “security issue”, I took my blog down and started from scratch with Jekyll. I really fell in love with the concept of creating your pages in markdown and generate the whole site with a site generator. But this attempt did not take off as well. Mostly because I was lazy and had no good ideas to write about. So after a while I also shutdown this blog and created a simple static site as some kind of a virtual “business card”.

Hugo - A New Hope

Some weeks ago I started playing around with Hugo. Hugo is a popular open-source static site generators. What started as a small project to replace my homepage ended up in a longer session than expected, because it was quite fun to rebuild my site with Hugo and start again with a Blog.

The existing Hugo themes are fine and look very good, but when you want to create your unique look and feel you have to create your own Hugo theme. There are good tutorials out there. I would recommend you to take the time and write your own theme. I think it’s the best way to learn Hugo and get some understanding how things work.

Which CSS Framework?

To build my own theme was a good change to get my rusty JavaScript and CSS skills updated. In the last web projects I used Bootstrap or Material Design, but this time I wanted to use a CSS framework with a smaller footprint.

So I decided to start with Skeleton. The downside with Skeleton is that the GitHub project is not active anymore. The last release was in December 2014 and there are open PR’s and issues. But besides that it was quiet easy to integrate and customize. Skeleton worked quite well, but the point that the project is not active anymore made me switch to Milligram. Milligram also provides a minimal setup of styles for a fast and clean starting point. So it was easy to adapt my design and switch to Milligram.

Hugo Build Pipeline with GitHub Actions

Next we need a build pipeline to publish new content. The easiest way is to host your site as a GitHub Page and look for GitHub Action which will publish your site. There are plenty of GitHub Actions in the Marketplace which help you to set up a workflow with GitHub Pages and Hugo.

I have an external provider which hosts my domain and emails. So this was no option for my. For that reason I have setup the following GitHub Actions:

• actions/checkout - The first step will check out my Hugo site from the GitHub repo.
• lowply/build-hugo - The next step will build the Hugo site in the directory public. You can specifyadditional parameters for the Hugo CLI like --minify, --baseURL, etc.
• SamKirkland/FTP-Deploy-Action - The last step will upload the generated site form the directory public to the SFTP server.

Note: You also have to add the file .git-ftp-include with the following content in your GitHub repo.

!public/

Because only tracked files will be published by default. This will guarantee that the generated Hugo site form the directory public will be uploaded.

If you have issues with self-signed certificate and SFTP you can add the flag insecure, which will not verify the server certificate.

Example Workflow

Here you can see the complete GitHub workflow in detail. This workflow will be triggered when changes are merged into the master branch. The SFTP password and username should be stored as GitHub secrets. It’s also a good idea to store the FTP server and port in a GitHub secrets as well when you have a public GitHub repository.

name: Build and Publish Hugo Site (MASTER)
on:
  push:
    branches: 
      - master
jobs:
  build:
    name: Publish Hugo Site (MASTER)
    runs-on: ubuntu-latest
    steps:
    - name: Checkout Source (GIT)
      uses: actions/checkout@v2
    - name: Hugo Build
      uses: lowply/build-hugo@v0.75.1
      with:
        # Hugo parameters like --buildDrafts, --baseURL, etc.
        # see https://gohugo.io/getting-started/usage/
        args: --minify
    - name: List files for debugging
      # For debugging list files from current directory to console
      run: ls
    - name: Upload Generated Site (SFTP)
      uses: SamKirkland/FTP-Deploy-Action@3.1.1
      with:
        # eg. replace with secret ${{ secrets.FTP_URI }}/page
        ftp-server: sftp://foo.bar:22/page
        ftp-username: ${{ secrets.FTP_USERNAME }}
        ftp-password: ${{ secrets.FTP_PASSWORD }}
        local-dir: public
        # ignore self-signed certificates
        git-ftp-args: --insecure

Source: https://gist.github.com/rueedlinger/c6aa02a41b39d6f1bc6c56bbe86ce5e1

Conclusion

My key takeaways are:

• When you want to learn Hugo take the time and try to create your own theme. It’s fun and youget a better understanding how Hugo works.
• Building your own theme gives you the maximum of flexibility how your site should look.
• Get some inspiration by other themes and look at the source code. Thisis a good way to learn how others have solved some of the problems you might ran into.

I hope this post was useful for you in some way. It was definitely fun for my to build a Hugo theme and play around with GitHub Actions.