Austin Barnes
October 8, 2022

Hugo GitPage - Creating a free website

Posted on October 8, 2022  •  4 minutes  • 686 words


Using Github pages, Github actions, and Hugo to create a static website for free.

Check out all of the configuration files on GitHub at the repository.



  1. Create a Public Repository
  2. Change Repository settings
    1. Custom Domain Name (Optional)
  3. Setup Hugo
  4. Picking a Theme
  5. Commit

Create a Public Repository

Go ahead and create a new repository. It is important that it is named something like

Next, navigate into the .github/workflows/ folder created by default. Create a file named example.yml (This should be the name as the

Add the following to the example.yml file

name: github pages

      - main  # Set a branch to deploy

    runs-on: ubuntu-20.04
      - uses: actions/[email protected]
          submodules: true  # Fetch Hugo themes (true OR recursive)
          fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod
      - name: Setup Node
        uses: actions/[email protected]
          node-version: '14'
      - name: Install dependencies
        run: |
          npm install postcss -D
          npm install -g postcss-cli
          npm install -g autoprefixer
      - name: Setup Hugo
        uses: peaceiris/[email protected]
          hugo-version: 'latest'
          # extended: true

      - name: Build
        run: npm i && hugo -D --gc #hugo --minify

      - name: Deploy
        uses: peaceiris/[email protected]
        #if: github.ref == 'refs/heads/master'
          github_token: ${{ secrets.SECRET_HUGO }}
          publish_dir: ./public

This will setup the GitHub page to build an environment that will support Hugo rather than the default GitHub pages service used Jekyll. The lines that run npm commands are additional, although necessary for some themes in order to run specific cross site scripts.

The github_token: ${{ secrets.SECRET_HUGO }} will be set under the Secrets -> Actions tab

Change Repository Settings

Go to the settings in the repository

  1. Create a new branch - I use gh-pages
  2. Under Pages tab
    • Under Build and Deployment -> Change source to Deploy from a branch and Branch to gh-pages
    • (Optional) Change custom domain name to your purchased domain name
    • Pages Settings

Custom Domain Name (Optional)

  1. Setting up DNS for Domain to allow GitHub Pages
  1. Modify config.toml file (Generated later with Hugo Setup)
  1. Create Static site name file

Setup Hugo

I recommend to clone down the repository created earlier, and generate the Hugo site into that folder structure. This will make commiting changes easier, and much more straightforward for this section.

Setting up Hugo (There are a few extra steps compared to normal, due to the Theme I will be demonstrating requiring POSTCSS)

This example will cover conducting the setup in Linux

  1. Commands to Setup npm versioning (Should be V.14) - Necessary for PostCSS

    1. sudo apt update
      sudo apt install nodejs npm
      curl -sL | sudo -E bash -
      sudo apt install nodejs
  2. Setup Hugo

    1. wget
      dpkg --install hugo_extended_0.98.0_Linux-64bit.deb
  3. Build site using Blist

    1. hugo new site blist # Can rename blist as needed
      cd blist 
      git clone themes/blist
      cp themes/blist/package.json ./package.json
      cp themes/blist/package-lock.json ./package-lock.json
      npm install
      npm i -g postcss-cli # Necessary for PostCSS
      echo "theme = \"blist\"" >> config.toml # Rename blist if you did so earlier
      hugo serve # Starts the Hugo server based on Static information within directory ran

Picking a Theme

If you wish to use another theme, I recommend searching online for freely available themes. Generally there isn’t too much change for setup in variation between theme to theme.


Now everytime you commit into the repository, it should update GH-Pages and populate the site!

Useful Resources

Follow me

I put a little bit of everything on here, so follow along in my journey if you wish