Host Hugo site to GitHub.

I wanted to host my personal Hugo blog completely free using GitHub Pages.

Initially, I faced several issues related to repository naming, GitHub Pages configuration, Git workflow conflicts, and deployment setup. After multiple fixes and testing, I successfully deployed the blog to:

https://sanjaybhowmick.github.io/

In this article, I’ll explain the complete process step-by-step so anyone can replicate it easily.

Step 1: Create Hugo Site Locally

I first created my Hugo website locally.

hugo new site myblog
cd myblog

Step 2: Configure Hugo

I updated the hugo.toml file.

baseURL = "https://sanjaybhowmick.github.io/"
publishDir = "public"
languageCode = "en-us"
title = "Sanjay Bhowmick"

[pagination]
  pagerSize = 6

[taxonomies]
  category = "categories"
  tag = "tags"

[params]
  author = "Sanjay Bhowmick"
  description = "My Notes"

[markup]
  [markup.goldmark.renderer]
    unsafe = true

[outputs]
  home = ["HTML", "JSON", "RSS"]
  section = ["HTML", "JSON", "RSS"]

Step 3: Create GitHub Repository

Initially, my repository name was: myblog. But GitHub Pages root domains only work when the repository name exactly matches: USERNAME.github.io

So I renamed the repository to: sanjaybhowmick.github.io

Step 4: Update Local Git Remote

After renaming the repository, my local Git remote still pointed to the old repository URL.

I updated it using:

git remote set-url origin https://github.com/sanjaybhowmick/sanjaybhowmick.github.io.git

Step 5: Create GitHub Actions Workflow

Inside the local Hugo project, I created this file:

.github/workflows/hugo.yml

Then added the deployment workflow:

name: Deploy Hugo site to Pages

on:
  push:
    branches:
      - main

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: true

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          submodules: recursive
          fetch-depth: 0

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v3
        with:
          hugo-version: latest
          extended: true

      - name: Build
        run: hugo --minify

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./public

  deploy:
    needs: build

    permissions:
      pages: write
      id-token: write

    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    runs-on: ubuntu-latest

    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Step 6: Configure GitHub Pages

In the GitHub repository settings: Settings → Pages

I selected: Source → GitHub Actions

This allows GitHub Actions to automatically build and deploy the Hugo website.

Step 7: Fix Git Push Issues

After renaming the repository, I encountered Git errors like:

Updates were rejected because the remote contains work that you do not have locally

Need to specify how to reconcile divergent branches

The simplest solution for my case was:

git push origin main --force

This synchronized my local repository with GitHub.

Step 8: Push Website to GitHub

I committed and pushed everything:

git add .
git commit -m "Initial Hugo blog deployment"
git push origin main

Step 9: Wait for Deployment

I checked deployment progress under:

GitHub Repository → Actions

After successful deployment, the website became live at:

https://sanjaybhowmick.github.io/

Step 10: Future Workflow

Now my blogging workflow is simple. Whenever I add new content:

hugo new posts/my-post.md
git add .
git commit -m "Added new blog post"
git push origin main

I write the article locally, then push changes, GitHub Actions automatically rebuilds and republishes the website.