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

Avoid Shaving the Yak with this concise checklist

Domain Provider

Prepare your domain (once per project)

  • 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

  • Install at your local machine.

Hugo

Install hugo on your machine (once)

  • 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)

  • 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.
  • 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.
  • 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.
  • 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.
  • 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
  • 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
  • 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.

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Martin Jahr

Digital Designer & life-long learner of computers & humans. Now up to create, coach and deliver learning deployment strategies in Germany where things are late.