Who is this written for?

If you also want to start your own blog and hope to:

• The source code is placed in a warehouse so that you can write it slowly
• The final website is automatically deployed to yourusername.github.io
• Try to avoid the pitfalls of GitHub Pages and Hugo as much as possible

Then this process will be easier.

I am using two warehouses here:

• Private warehouse: blogsource
• Public warehouse: yourusername.github.io

Among them, it is best to use yourusername.github.io directly as the name of the public warehouse. If it is your first time to use GitHub Pages, it is recommended to follow this step, which is the easiest.

Get ready before you start

Install these things first:

• Hugo
• Git
• An editor you are comfortable with, such as VS Code

Then find a local folder specifically to store the blog project, for example, mine is D:\MyBlog.

a little reminder

Throughout the process, try to modify files locally and then push them up through Git. Don’t make changes locally for a while and then go to the GitHub webpage for a while, otherwise it will be easy to mess up the status of the warehouse.

overall idea

The structure of this blog is actually very simple:

1. blogsource is used to store Hugo source code
2. yourusername.github.io Used to place the generated static web page
3. Write articles locally and push source code
4. GitHub Actions automatically build and deploy to public repositories

If you don’t want to automate it at first, you can deploy it manually first, make sure the website can run, and then add Actions.

1. Initialize the Hugo project

First enter the directory where you plan to put your blog in the terminal, for example:

cd D:\MyBlog

Then create the Hugo project:

hugo new site blogsource
cd blogsource
git init
git remote add origin https://github.com/yourusername/blogsource.git

Replace yourusername with your own GitHub username here.

2. Add a theme

I am using the LoveIt theme here, you can also change it to your favorite theme.

git submodule add https://github.com/dillonzq/LoveIt themes/LoveIt

The advantage of using submodules is that it will be more convenient to update the theme later.

3. Configure hugo.toml

First write the most basic configuration:

baseURL = "https://yourusername.github.io/"
title = "My Blog"
theme = "LoveIt"
publishDir = "public"

There are two places to pay special attention to here:

• baseURL You need to change it to your own address, and it is recommended to keep the last one /
• publishDir = "public" means that the static files generated by Hugo will be placed in public/

4. Create a test article first

First make sure Hugo itself is working properly:

hugo new posts/hello-world.md

Then edit content/posts/hello-world.md and write it like this:

+++
title = "Hello World"
date = "2024-01-01T00:00:00+08:00"
draft = false
+++

This is my first blog post.

If there is draft = true in your article, it will not be displayed by default. It is easy to forget this place.

5. Local preview

Run in the project root directory:

hugo server -D

Then open:

http://localhost:1313

If you can see the homepage and the test article just now normally, it means that the local Hugo is no longer a problem.

6. First push the source code to the private warehouse

This step is to put the Hugo source code into the blogsource warehouse.

If the remote warehouse configuration is missed

You can delete the old one first:

git remote remove origin
git remote add origin https://github.com/yourusername/blogsource.git

Submit and push

git add .
git commit -m "Initial commit: Hugo project with theme"
git branch -M main
git push -u origin main

If you have a brand new empty repository, this is usually enough, not necessarily --force.

After the push is completed, you can go to GitHub to take a look:

https://github.com/yourusername/blogsource

Confirm that the documents have been uploaded.

7. First manually deploy once to the public warehouse

If you want to verify that the entire process can run smoothly, you can deploy it manually first.

First generate static files:

hugo --minify

Then enter public/ and push it to the public warehouse as a separate warehouse:

cd public
git init
git add .
git commit -m "Deploy to GitHub Pages"
git remote add origin https://github.com/yourusername/yourusername.github.io.git
git branch -M main
git push -u origin main --force

The reason why --force is common here is because public/ This warehouse is essentially a generated product, and it is usually most worry-free to directly cover it as a whole.

8. Configure GitHub Pages

Go to the public warehouse yourusername.github.io and open:

Settings -> Pages

Then confirm:

• Branch: main
• Folder: / (root)

After a minute or two, visit:

https://yourusername.github.io

If the website can be opened, it means that the most basic deployment link has been passed.

9. Do automated deployment again

After you successfully deploy manually, it will be more stable to use GitHub Actions.

The goal is: in the future, you only need to push the source code to blogsource, and GitHub will automatically build and deploy it.

10. Generate SSH keys

Run in Git Bash:

ssh-keygen -t ed25519 -C "actions-deploy-key" -f ~/.ssh/gh-pages-key

There are two files after generation:

• Private key: ~/.ssh/gh-pages-key
• Public key: ~/.ssh/gh-pages-key.pub

You can view them separately:

cat ~/.ssh/gh-pages-key
cat ~/.ssh/gh-pages-key.pub

11. Configure the key to GitHub

Add public key to public repository

Enter yourusername.github.io warehouse:

Settings -> Deploy keys -> Add deploy key

Then fill in:

• Title: ACTIONS_DEPLOY_KEY
• Key: Paste the content of gh-pages-key.pub
• Check Allow write access

Add a private key to the source code repository

Enter blogsource warehouse:

Settings -> Secrets and variables -> Actions -> New repository secret

Then fill in:

• Name: ACTIONS_DEPLOY_KEY
• Value: Paste the complete content of gh-pages-key

12. Add GitHub Actions workflow

Create a new file in the project:

.github/workflows/deploy.yml

You can refer to the following content:

name: Deploy Hugo Site to GitHub Pages

on:
  push:
    branches: ["main"]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          submodules: true
          fetch-depth: 0

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: "0.145.0"
          extended: true

      - name: Build
        run: hugo --minify --gc

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
          external_repository: yourusername/yourusername.github.io
          publish_dir: ./public
          publish_branch: gh-pages
          keep_files: false

Also remember to replace yourusername with your own username here.

13. Verify whether the workflow is effective

Submit the workflow file:

git add .github/workflows/deploy.yml
git commit -m "Add GitHub Actions workflow"
git push origin main

Then go to GitHub’s Actions page to see:

• Is there a new workflow?
• Is the latest run green?
• If it fails, click in to view the log directly.

14. It will be much easier to write articles later

After the automated deployment is completed, the subsequent update of the blog is basically this process:

1. Write or modify articles in content/
2. Local preview confirms there is no problem
3. Submit source code
4. Push to blogsource
5. Wait for GitHub automatic deployment to complete

The command is probably:

git add .
git commit -m "Update blog content"
git push origin main

After pushing it, GitHub will automatically deploy the static page to yourusername.github.io.

One final sentence

If you just want to get your blog running first, then complete the following steps:

1. Create a Hugo project
2. Add topic
3. local preview
4. Manual deployment was successful once

After this link is established, and automation is added, the mentality will be much more relaxed, and it will be less likely to be discouraged by a bunch of Git and Actions errors.