How to Deploy Hugo on Github (with Blowfish Theme)

If you haven’t used Hugo before, you need to understand how to install Hugo on your local machine. You can check Hugo is installed by running the command hugo version.

If you haven’t used Go and Git before, you’ll need to know about installing Git on your local machine, and then install Go on your local machine from the official Go website. The version should be 1.23.0 or above.

Create a Git Project

#

Create a git project for your website link. The repo name should be in the format <username>.github.io, which will also serve as the entry point for your website domain. Then, in your project folder, enter git init -b main to initialize your git repo.

Tips: if you want to make more repo’s website, use <username>.github.io/<repo_name> to load your website.

Deploy Git and Prepare for Github Pages Service

#

This article won’t delve too much into the related usage of synchronizing Git and Github. After the above steps, your default branch will be main. (with git init -b main) Next, we’ll need a branch called gh-pages; This branch will be used for future workflows, which is the Action service provided by Github.

branch : main gh-pages

.gitignore File

#

Files to ignore:

#others
node_modules
.hugo_build.lock

# Hugo
public

Create a Workflow

#

Create an empty folder named .github/workflows in your directory, then name this filegh-pages.yml. You can see in the code below:

# .github/workflows/gh-pages.yml

name: GitHub Pages

on:
  push:
    branches:
      - main

jobs:
  build-deploy:
    runs-on: ubuntu-20.04
    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}
    steps:
      - name: Checkout
        uses: actions/checkout@v3
        with:
          submodules: true
          fetch-depth: 0

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: "latest"

      - name: Build
        run: hugo --minify

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        if: ${{ github.ref == 'refs/heads/main' }}
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_branch: gh-pages
          publish_dir: ./public

After you push the relevant data tomain, the workflow will automatically create build-deploy, and finally set up the web content on gh-pages.

!!Note: You need to enable read and write permissions for automation in your repo and choose the branch for displaying Pages externally to set up the website.

How to Adjust Action Write Permissions

#

First, enable write permissions for Actions:

Settings->Code and automation->Actions->General-> [Side page]->Workflow permissions-> Select the radio button “Read and write permissions”->Click “Save” to store changes

Next, select your branch which using for Github Page：

Settings->Code and automation->Pages->[Side page]-> Build and deployment-> Branch->Drop down to change “main” to “gh-pages”->Click “Save” to store changes

Create a New Site

#

If you plan to create website data in an already created empty folder, use hugo new site . to create a basic Hugo project. (If the folder already has content, you can use --force to force initialization: hugo new site . --force)

If you don’t have an empty website project folder yet, you can use the hugo new site mywebsite command to create a new Hugo site in a new mywebsite directory.

Next, download the blowfish theme and choose the channel you want to use. The author used manual file copying, which means directly downloading the latest version of the source code and extracting it to ./theme/blowfish.

Set Up the Theme Configuration Files

#

In your website’s root directory, delete the hugo.toml file automatically generated by Hugo. Instead, we’ll use the *.toml files that exist in the theme. Move the relevant suffix files from ./theme/blowfish/config/_default to the ./config/_default/ directory in the web root directory. This will ensure your theme settings are accurate and allow you to easily customize the related theme.

‼Note: If a module.toml file already exists in the project, do not overwrite it!

After you’ve copied these files, your config directory should look like this:

config/_default/
├─ hugo.toml
├─ languages.en.toml
├─ markup.toml
├─ menus.en.toml
├─ module.toml  # Installed via Hugo modules
└─ params.toml

‼Important: If you didn’t install Blowfish using Hugo modules, you must add theme = "blowfish" to the hugo.toml file. (Or you should see # theme = "blowfish" # UNCOMMENT THIS LINE in the hugo.toml file, just remove the comment to apply the related theme)

Next Steps

#

The basic Blowfish installation is now complete. Please continue reading the original tutorial’s Getting Started Guide to learn more about theme configuration. I will also write more articles in the future to introduce simple website settings.