Introduction

Crafting your blog with Hugo and effortlessly deploying it on Github Pages using Github Actions. This guide will walk you through the process.If you already have a site, jump straight to Configuring Github Actions for Github Pages Deployment part

Make sure you have Git and ghcli installed, and your GitHub account is linked. Otherwise, you may encounter some nasty errors while running commands in this blog. GitHub CLI, Git.

Step 1: Setting up Hugo

Mac:

brew install hugo

Linux:

sudo snap install hugo
sudo snap connect hugo:removable-media
sudo snap disconnect hugo:removable-media

The last two commands to enable or revoke access to removable media

Windows:

its 2024 now and you still using windows, switch to linux already 😒.

Step 2: Create a New Site with Hugo

hugo new site <site_name> -f yml

This command conjures up a directory with Hugo templates, And don’t worry about toml - we are sticking with the yml for this blog as it is easy to use.

Step 3: Install Theme

  1. Go to Hugo Themes
  2. Pick a theme that vibes with your style.
  3. Navigate to the theme’s source code (GitHub repo).

Installing Theme:

git clone <theme_repo_url> themes/<theme_name> --depth=1

The –depth=1 ensures you’re not drowning in commit history.

Configure Theme in config.yml:

theme: <theme_name>

Smooth. This will set a basic sit for your blog to be deplyed on GitHub.

Configuring Github Actions for Github Pages Deployment

Initialize Git Repository:

echo "# README" >> README.md
git init
git add README.md
git commit -m "first commit"
git branch -M main
git remote add origin <path_to_your_git_repo>
git push -u origin main

To link your local Git repository with a remote repository on GitHub, follow these steps:

Copy Repository URL:

  • On GitHub, navigate to your repository.
  • Click on the “Code” button, and copy the repository URL (HTTPS or SSH).
  • Open a terminal or command prompt.
  • Navigate to the directory of your local Git repository.
  • Run the following command, replacing <repository_url> with the URL you copied:

If you’re using HTTPS: git remote add origin <repository_url>

If you’re using SSH: git remote add origin git@github.com:/<repository_name>.git

Verify the Connection:

  • To verify that your local repository is connected to the remote repository, you can run:
git remote -v

This command should display the fetch and push URLs for the origin remote.

Manually Add gh-pages Branch:

git checkout -b gh-pages

this branch is must for GitHub pages to work.

Configure Workflow Permissions:

  • Adjust workflow permissions in the Github settings.

Allow read and write permissions under Settings > Actions > General > Workflow permissions

Add a .github/workflows/deploy.yml file under the project root directory

name: Publish to GH Pages
on:
  push:
    branches:
      - main
  pull_request:

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout source
        uses: actions/checkout@v3
        with:
          submodules: true

      - name: Checkout destination
        uses: actions/checkout@v3
        if: github.ref == 'refs/heads/main'
        with:
          ref: gh-pages
          path: built-site

      - name: Setup Hugo
        run: |
          curl -L -o /tmp/hugo.tar.gz 'https://github.com/gohugoio/hugo/releases/download/v0.110.0/hugo_extended_0.110.0_linux-amd64.tar.gz'
          tar -C ${RUNNER_TEMP} -zxvf /tmp/hugo.tar.gz hugo
      - name: Build
        run: ${RUNNER_TEMP}/hugo

      - name: Deploy
        if: github.ref == 'refs/heads/main'
        run: |
          cp -R public/* ${GITHUB_WORKSPACE}/built-site/
          cd ${GITHUB_WORKSPACE}/built-site
          git add .
          git config user.name '<GitHubUserName>'
          git config user.email '<GitHubEmail>'
          git commit -m 'Updated site'
          git push

  • The first step checks out my repository under $GITHUB_WORKSPACE and submodules:true ensures that our submodule for the theme repository is fetched as well

  • The second step allows us to reference the gh-pages branch via the $GITHUB_WORKSPACE/built-site directory, where our static sites will be stored in (Refer to the Deploy step)

  • The third and fourth steps involve installing hugo and building the static pages in the public directory with the hugo command

  • The last step copies the static sites into ${GITHUB_WORKSPACE}/built-site and pushes the changes to the referenced branch gh-pages, which is a special branch that Github recognizes and uses to publish to your Github Pages site

Note: the content will be deployed to https://.github.io/<repository_name>/ by default if not configured otherwise. Update the base_url in config.yml to “https://.github.io/<repository_name>/”

After creating the file , push the commits and Github actions should take care of delpoying it automatically, you should end up with this.

Can&rsquo;t Load Image