DEV Community

Cover image for How to Deploy a Static Website with Hugo and GitHub Pages
yang yaru
yang yaru

Posted on

How to Deploy a Static Website with Hugo and GitHub Pages

Introduction

In this guide, I'll walk you through the process of creating and deploying a static website using Hugo and GitHub Pages. Hugo is a fast and modern static site generator written in Go, and GitHub Pages provides free hosting for static websites.
This is my website.https://yaruyng.github.io/

yaruyng's blog website

Prerequisites

Before we begin, make sure you have:

  • Git installed on your computer
  • A GitHub account
  • Basic knowledge of command line operations
  • Go built Hugo from source

Step 1: Install Hugo

For ubuntu users :

Before we begin,we should check the architecture og Ubuntu machine to ensure we download the correct package.

uname -i
Enter fullscreen mode Exit fullscreen mode

if you see the following, it indicates that you are running a 64-bit Ubuntu installation.

x86_64
Enter fullscreen mode Exit fullscreen mode

Vist the Hugo release page to find the last version of Hugo and copy the url.

Hugo is available in three editions:standard,extended,and extended/deploy.While the standard edition provides core functionality,the extended and extended/deploy editions offer advanced features.Many modern Hugo themes require the Extended edition,so I recommend using this edition.

cd ~
wget https://github.com/spf13/hugo/releases/download/v0.140.1/hugo-extended_0.140.1_amd64.deb
Enter fullscreen mode Exit fullscreen mode

Now,you can install the dpkg by entering the following content.

sudo dpkg -i hugo*.deb
Enter fullscreen mode Exit fullscreen mode

Verify the installation:

hugo version
Enter fullscreen mode Exit fullscreen mode

Step 2: Fork a Theme

For this example, we'll use the popular PaperMod theme:

You can directly fork the theme repository and modify the repository name to yourgithubusername.github.io

Step 2: Customize a Theme

git clone https://github.com/yourgithubusername/yourgithubusername.github.io.git
Enter fullscreen mode Exit fullscreen mode

Update your config.toml file:

baseURL = 'https://yourusername.github.io/'
languageCode = 'en-us'
title = 'My Blog'
theme = 'PaperMod'
Enter fullscreen mode Exit fullscreen mode

Step 4: Create Content

Create your first post:

You can modify the template in the theme or create your own md file.

vim content/english/blog/post-1.md
Enter fullscreen mode Exit fullscreen mode

Edit the created file at content/english/blog/post-1.md:

---
title: "My First Post"
date: 2024-12-26
draft: false
---

This is my first blog post using Hugo!
Enter fullscreen mode Exit fullscreen mode

Step 5: Test Locally

Run the Hugo server to preview your site:

hugo server -D
Enter fullscreen mode Exit fullscreen mode

Visit http://localhost:1313 in your browser to see your site.

Step 6: Configure GitHub Pages

Create a .github/workflows/hugo.yml file in your project:

# Sample workflow for building and deploying a Hugo site to GitHub Pages
name: Deploy Hugo site to Pages

on:
  # Runs on pushes targeting the default branch
  push:
    branches:
      - main

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: "pages"
  cancel-in-progress: false

# Default to bash
defaults:
  run:
    shell: bash

jobs:
  # Build job
  build:
    runs-on: ubuntu-latest
    env:
      HUGO_VERSION: 0.137.1
    steps:
      - name: Install Hugo CLI
        run: |
          wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb \
          && sudo dpkg -i ${{ runner.temp }}/hugo.deb          
      - name: Install Dart Sass
        run: sudo snap install dart-sass
      - name: Checkout
        uses: actions/checkout@v4
        with:
          submodules: recursive
          fetch-depth: 0
      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v5
      - name: Install Node.js dependencies
        run: "[[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci || true"
      - name: Build with Hugo
        env:
          HUGO_CACHEDIR: ${{ runner.temp }}/hugo_cache
          HUGO_ENVIRONMENT: production
          TZ: America/Los_Angeles
        run: |
          hugo \
            --gc \
            --minify \
            --baseURL "${{ steps.pages.outputs.base_url }}/"          
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./public

  # Deployment job
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4
Enter fullscreen mode Exit fullscreen mode

Setup Github

Visit your GitHub repository. From the main menu choose Settings > Pages. In the center of your screen you will see this:

pages

From the main menu choose Settings > Action > General.In the bottom of your screen you will see this:

permission

Step 7: Deploy

Push your code to GitHub:

git add .
git commit -m "Initial commit"
git branch -M main
git remote add origin https://github.com/yourusername/yourusername.github.io.git
git push -u origin main
Enter fullscreen mode Exit fullscreen mode

Final Steps and Verification

  1. Wait a few minutes for GitHub Actions to complete the deployment
  2. Visit https://yourusername.github.io to see your live site
  3. Any future pushes to the main branch will automatically trigger a new deployment ## Common Issues and Solutions
  4. 404 Error

-Check if your baseURL in config.toml matches your GitHub Pages URL
-Ensure your repository name follows the format: username.github.io

  1. Missing Theme

-Verify that the theme is properly initialized as a submodule
-Check if the theme name in config.toml matches the theme directory name

  1. Build Failures

-Check GitHub Actions logs for specific error messages
-Ensure all dependencies are properly specified in the workflow file

Conclusion

You now have a fully functional static website powered by Hugo and hosted on GitHub Pages! This setup provides a robust foundation for blogging, documentation, or any other static website needs.

Next Steps

-Customize your theme

-Add more content

-Configure custom domain

-Enable comments using Disqus or other platforms

-Add analytics tracking

-Remember to regularly commit and push your changes to keep your site updated.

Happy blogging! 🚀

Speedy emails, satisfied customers

Postmark Image

Are delayed transactional emails costing you user satisfaction? Postmark delivers your emails almost instantly, keeping your customers happy and connected.

Sign up

Top comments (0)

Billboard image

The Next Generation Developer Platform

Coherence is the first Platform-as-a-Service you can control. Unlike "black-box" platforms that are opinionated about the infra you can deploy, Coherence is powered by CNC, the open-source IaC framework, which offers limitless customization.

Learn more

👋 Kindness is contagious

Explore a sea of insights with this enlightening post, highly esteemed within the nurturing DEV Community. Coders of all stripes are invited to participate and contribute to our shared knowledge.

Expressing gratitude with a simple "thank you" can make a big impact. Leave your thanks in the comments!

On DEV, exchanging ideas smooths our way and strengthens our community bonds. Found this useful? A quick note of thanks to the author can mean a lot.

Okay