42 Steps from Zero to an Automated Website built with Hugo and Github

Avoid Shaving the Yak with this concise checklist

Do you know the phrase “Shaving a Yak”? This phrase was coined at the MIT in the Nineties, and refers to a set of seemingly unneccessary steps that you have to do before you can do what you really want to achieve. More often than not, I feel that way when trying out some new technology or when assembling parts of my tech stack in a new way. So many different prerequisites are to fulfill before you can start with exactly that use case that you had in mind!

One of those yak-shaving pitfalls is to “just set up a quick web site for a small project”. If you don’t do that every day for a living (and even then), you get entangled in setup prescriptions from your domain provider, your web authoring tool and possibly your repository if you dare to use one.

Over time, a standard configuration of tools emerged as the perfect mix for me. It keeps me consistent but also allows some flexibility. This stack is the combination of Markdown texts, Hugo Web site generation, and Github as my version repository and site deployer.

The configuration is not really difficult but you have to use all the right nuts and bolts in the correct sequence to get a result without too much of hassle. And so, rather for my personal needs than for you, dear reader, I created that list of steps that need to be taken when waking up in the night with a new web site project idea.

I assume that you have a some vague knowledge about markdown, git, command line tools, and software installation, which allows you to follow my concise list — though I tried to be as detailed as possible. Enjoy!

Domain Provider

Prepare your domain (once per project)

• Get a domain xyz.org (or .com or whatever) from a provider where you can edit DNS settings.
• Create a www.xyz.org subdomain. Be careful to distinguish these two URLs during this setup.
• Create a permanent redirect (Code 301) from xyz.org to www.xyz.org .
• Create a CNAME entry at the DNS settings at your www.xyz.org domain that points to xyz.github.io.(keep care to add the trailing period, but maybe the domain provider does that for you.)
• Switch SSL settings on for the xyz.org domain (depends on provider. Is typically used for sub domains, too.)

Markdown Editor

Prepare your Working Environment

• Select a Markdown editor of your choice (make sure you can edit front matters with it, too). If you are tech-savvy, you can use MS Visual Studio, otherwise there are a lot of editors out there. Try Mark Text (easy to use, some minor bugs), or Typora, or others depending on your personal preferences.
• Install at your local machine.

Hugo

Install hugo on your machine (once)

• Go to https://github.com/gohugoio/hugo/releases and download the hugo or hugo_extended zip or gz file for your machine (typically Windows-64bit or macOS-64bit)
• Unpack the zip/gz file, then delete the zip/gz file. You should now have a hugo.exe (windows) or a hugo (macOS) command file.
• Add the location where you did this to your PATH environment variable to run hugo form anywhere. (If that exceeds your system knowledge, you have to call the app with the complete path like c:\mydocuments\mydownsloads\hugo\hugo.exe when you use it on the command line in another directory.)

Github

Prepare your Working Environment (once)

• Create a github account yourgitaccount. Confirm all emails that are needed to get running.
• Go to Settings, then Developer Settings, then Personal access token in the account’s menu. Create a token with the name hugo_publishing, then mark the repo checkbox. Keep the copied value at a safe place, you will never see it again from Github.
• Install Github Desktop (or git bash for command line friends) on your computer. Sign in with your github account.

Prepare the Source Code Project (once per project)

• Create a private github project yourgitaccount/xyz.org. Click “Add a README file” to initialize the code repo.
• Go to project settings, then secrets. Add a secret named HUGO, and paste the value of the personal access token you saved into the value box.
• In project settings, check that in the Actions panel “Allow all actions” is selected (should be default).
• Clone this project to local workspace.

Prepare the Hugo Environment (once per project)

• Go into the directory where the cloned project resides and run hugo new site . --force .
• Select a hugo theme and clone it as git submodule: e.g. for the Reveal theme use git submodule add git@github.com:dzello/reveal-hugo.git themes/reveal-hugo .
• Edit config.toml - change baseURL to https://www.xyz.org .
• Create minimal content to have something to show on your website. Typically you would add an content/_index.md file with something in it. Read your Hugo Themes documentation how to get started.

Prepare the Publishing Project (once per project)

• Create a public github project yourgitaccount/xyz.github.io . Click “Add a README file” to initialize the code repo.
• Go to project settings, then options. In the Github Pages section, check the following setups:
• Ensure that Branch:main and /(root) is selected.
• Add www.xyz.org to the custom domain field. Github needs some time to set up a TLS certificate (about 15 minutes).
• When the github Pages section now shows “Your site is published at http://www.xyz.org", the setup is complete. Check the “Enforce HTTPS” box at the end of that section.
• If you open your domain site https://www.xyz.org now in the browser, you should see the README.md file’s content. You might encounter a security warning of your browser, which will stay until the TLS certificate is globally distributed. This can take up to a day, but is typically done in an hour max.

Prepare the Publishing Workflow (once per project)

• Go back to your local Code project clone yourgitaccount/xyz.org .
• Create a .github directory. In it, create a workflows directory.
• Create a main.yml file in that directory and copy this code

name: CommitWebSite
on: push
jobs:
  deploy:
    runs-on: ubuntu-18.04
    steps:
      - name: Git checkout
        uses: actions/checkout@v2
        with:
          submodules: true
          fetch-depth: 0
      - name: Setup hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: "0.68.3"
      - name: Build
        run: hugo --minify
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          personal_token: ${{ secrets.HUGO }}
          external_repository: yourgitaccount/xyz.github.io
          publish_dir: ./public
          keep_files: true
          user_name: yourgitaccount
          user_email: info@xyz.org
          publish_branch: main
          cname: www.xyz.org

• You might want to change hugo-version, if your theme relies on another release.
• Set external_repositoryto the name of your publishing repo.
• Set user_name to your git account name.
• Set user_email to the email you will use as generic web site email address.
• set cname to the source domain www.xyz.org

Run the Web Site Automation for the First Time

• You’re all settled now with configuration. In Github Desktop (or git command line, if you feel more like typing) stage and commit all changes in that repo, then push to remote.
• Check the Actions panel in the Source code project. You should see a green check at the workflow that indicates deployment success
• Check the Code panel in the Publishing project. You should see some files and directories, which depend on the theme you chose. At least there must be an index.html file.

Start Editing your Web Site for Real

• Now point your Markdown Editor to the content directory of your project clone. Create what you planned in the first place, according to the theme’s prescriptions. Whenever you changed something, stage, commit and push, and after some seconds, the effect becomes visible on your web site.

Be aware that action resources are constraint in the free versions of Github. So you might to have to wait a little if you are very busy in creating content. In the long run you will start working with branches, especially when working with multiple persons on the same project. But this is another story I will tell later.