[Github] 1. Deploy GitHub Blog Site

GoodyHao included in Github Deploy English

2025-09-10 1033 words 5 minutes

[Github] 1. Deploy GitHub Blog Site

1. intro

GitHub Pages is a static site hosting service that takes HTML, CSS, and JavaScript files straight from a repository on GitHub, optionally runs the files through a build process, and publishes a website.

2. pre-work

2.1 create a repository

Create a repository named your_github_username.github.io, where your_github_username is your GitHub username. For example, if your GitHub username is octocat, the repository name should be octocat.github.io.

2.2 hugo install

Download the latest version of Hugo from the official Hugo releases page

3. create a blog site

3.1 hugo init site

1
2
3
4
5
6
7
8
# create directory
mkdir your_github_username.github.io
# cd to directory
cd your_github_username.github.io
# init site
hugo new site .
# git init, make sure it's a git repository
git init

3.2 add a theme

1
2
3
4
5
6
7
8
9
# add a theme, here we use LoveIt theme.
git submodule add https://github.com/dillonzq/LoveIt.git themes/LoveIt
# now the git is main branch which is not stable, we need to checkout to the latest stable version.
cd themes/LoveIt
git checkout v0.3.0
cd ../..
# now, there should be a .gitmodules file in your directory. if not, you need to run `git init` first.
# copy the exampleSite config file to the root directory
cp themes/LoveIt/exampleSite/hugo.toml .

3.3 modify the config file

modify the config file hugo.toml

3.3.1 bashURL

1
baseURL = "https://gooddayday.github.io"

3.3.2 themes directory

1
2
3
# themes directory
# 主题目录
themesDir = "./themes"

3.3.3 website title

1
2
3
# website title
# 网站标题
title = "GoodyHao's Blog"

3.3.4 website images

1
2
3
# website images for Open Graph and Twitter Cards
# 网站图片, 用于 Open Graph 和 Twitter Cards
images = ["/logo.jpg"]

3.3.5 website icon

put icon file in the static directory

3.3.6 gitRepo

modify the gitRepo to your public git repo url

1
2
3
# public git repo url only then enableGitInfo is true
# 公共 git 仓库路径，仅在 enableGitInfo 设为 true 时有效
gitRepo = "https://github.com/GOODDAYDAY/GOODDAYDAY.github.io"

4. github deploy

4.1 create a workflow file

create a file .github/workflows/deploy.yaml, and add the following content:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
name: Deploy Hugo to GitHub Pages
on:
  push:  # 触发条件：推送代码到master分支
    branches:
      - master
jobs:
  build-and-deploy:
    runs-on: ubuntu-latest  # 使用Ubuntu环境
    steps:
      # 1. 检出仓库代码（递归拉取主题submodule）
      - uses: actions/checkout@v4
        with:
          submodules: true
      
      # 2. 安装Hugo（使用extended版本，支持SASS）
      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: 'latest'  # 或指定版本（如'0.147.2'）
          extended: true
      
      # 3. 缓存依赖（加快后续构建速度）
      - uses: actions/cache@v3
        with:
          path: |
            resources/_gen
            public
          key: ${{ runner.os }}-hugo-${{ hashFiles('**/go.sum') }}
          restore-keys: |
            ${{ runner.os }}-hugo-
      
      # 4. 构建Hugo站点（开启压缩）
      - name: Build Hugo site
        run: hugo --minify
      
      # 5. 部署到GitHub Pages（自动推送public目录到gh-pages分支）
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN  }}  # GitHub自动提供的Token（无需手动创建）
          publish_dir: ./public  # 指向Hugo生成的静态文件目录
          force_orphan: true  # 强制创建新提交（避免分支历史混乱）

github repository settings -> pages -> source -> select gh-pages branch and / (root) folder -> save
- if gh-pages branch not exist, need to push code to github first

need to set token

generate new token with repo and workflow permissions

add token to github secrets with name TOKEN_GITHUB

4.2 push code to github

1
2
3
4
5
6
# add all files
git add .
# commit
git commit -m "first commit"
# push to github
git push -u origin master

4.3 check the workflow

check the workflow in github actions

5. access the blog site

access the blog site with https://your_github_username.github.io, for example, https://gooddayday.github.io

6. others

6.1 add new post

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
# create a new post
hugo new posts/first-post.md
# edit the post
vim content/posts/first-post.md
# after edit, need to set the post as published
# set draft = false
# then commit and push to github
git add .
git commit -m "add first post"
git push

if you want to add images to the post, need to put the images in the static directory, for example, static/images/first-post-image.png, then you can access the image with /images/first-post-image.png in the post.

6.2 gitignore

create a .gitignore file in the root directory, and add the following content:

1
public/*

we don’t need to push the public directory to github, because it will be generated by hugo in the workflow.

6.3 tag & category generate

tag and category will be generated automatically by hugo, no need to create them manually.
But if no index.html shown below, you need to add templates.

just copy the themes/LoveIt/layouts/taxonomy/list.html to the different path and rename it to layouts/taxonomy/tag.html and layouts/taxonomy/category.html

and then, run hugo server to check if the result has index.html like the picture below:

6.4 setup comment system with giscus

By default, the LoveIt theme uses Valine comment system, but we recommend using Giscus which is based on GitHub Discussions. Giscus is free, stable, and stores comment data in your own GitHub repository.

6.4.1 disable other comment systems

First, make sure other comment systems are disabled in hugo.toml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# Disable Valine
[params.page.comment.valine]
enable = false

# Disable Disqus
[params.page.comment.disqus]
enable = false

# Disable Gitalk
[params.page.comment.gitalk]
enable = false

6.4.2 enable GitHub Discussions

Go to your GitHub repository settings: https://github.com/your-username/your-username.github.io/settings
Navigate to Features section
Check the Discussions checkbox to enable it

6.4.3 configure giscus

Visit giscus.app to generate configuration
Fill in the repository field: your-username/your-username.github.io
Click The giscus app is installed, otherwise visitors will not be able to comment and react. and install giscus to your repository.

6.4.4 update hugo.toml

Add the giscus configuration to your hugo.toml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
[params.page.comment.giscus]
enable = true
repo = "your-username/your-username.github.io"
repoId = "your-repo-id-from-giscus"
category = "General"  # or your chosen category
categoryId = "your-category-id-from-giscus"
lang = ""  # empty for auto-detection
mapping = "pathname"
reactionsEnabled = "1"
emitMetadata = "0"
inputPosition = "bottom"
lazyLoading = false
lightTheme = "light"
darkTheme = "dark"

data like repoId and categoryId can be found in the giscus configuration you generated earlier.

Contents

[Github] 1. Deploy GitHub Blog Site

[Github] 1. Deploy GitHub Blog Site

1. intro

2. pre-work

2.1 create a repository

2.2 hugo install

3. create a blog site

3.1 hugo init site

3.2 add a theme

3.3 modify the config file

3.3.1 bashURL

3.3.2 themes directory

3.3.3 website title

3.3.4 website images

3.3.5 website icon

3.3.6 gitRepo

4. github deploy

4.1 create a workflow file

4.2 push code to github

4.3 check the workflow

5. access the blog site

6. others

6.1 add new post

6.2 gitignore

6.3 tag & category generate

6.4 setup comment system with giscus

6.4.1 disable other comment systems

6.4.2 enable GitHub Discussions

6.4.3 configure giscus

6.4.4 update hugo.toml