Preparation
Install Git
- Download and install: https://git-scm.com
- After the installation is complete, the right-click menu should show “Git Bash Here”
- Verify the installation:
1
2
|
# Open power shell to check if git is installed successfully
git --version
|
Install Hugo (extended version recommended)
Just enter in power shell
1
2
3
4
5
6
|
# install
winget install Hugo.Hugo.Extended
# To uninstall
winget uninstall --name "Hugo (Extended)"
# Check if Hugo is installed successfully (restart the terminal or restart the computer)
hugo version
|
Register for GitHub and create a repository
- Github registration: https://github.com
- Create a repository with the same name as your username, for example:
1
|
<Github user name>.github.io
|
Create a Hugo blog project Create a Hugo blog project
Find a local location to store the source code
1
2
3
4
5
6
7
8
|
# Create a folder
mkdir blog
# Open the folder
cd blog
# Use hugo to create a folder (here is your code repository)
hugo new site <your folder name>
#Open your folder
CD <your folder name>
|
Add theme PaperMod
- Here we use Theme - PaperMod as an example
- In the current folder directory powershell:
1
2
3
4
|
# git initialize local warehouse
git init
# Download PaperMod to your local computer
git submodule add https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod
|
If git submodule add doesn’t work, you can browse to the PaperMod homepage and click <>Code to download the zip file. Compress the file, rename it to PaperMod, and copy and paste it into the current themes directory.
Copy and paste the following code into hugo.toml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
|
baseURL = 'https://<Your username>.github.io/'
languageCode = 'zh-cn'
title = '<my blog>'
theme = 'PaperMod'
[params]
defaultTheme = "auto"
# Be careful not to wrap the line under homeInfoParams, otherwise hugo server may not open (delete this comment when copying)）
homeInfoParams = { Title = "Hello, I'm <your username> ", Content = "Welcome to my blog homepage: Personal / Blog / Tutorial " }
[[menu.main]]
name = "Persional"
url = "/posts"
weight = 1
[[menu.main]]
name = "Tutorial"
url = "/docs"
weight = 2
[[menu.main]]
name = "Study"
url = "/study"
weight = 3
|
- baseURL: the link to access your personal web page;
- url: The link is to the folder under content in the current directory;
- weight: indicates the web page deployment location
- Subsequent modifications based on personal circumstances
Writing your first article
1
2
|
# Enter in the current root directory
hugo new posts/hello-hugo.md
|
Use hugo new to link the script to create the above link in markdown:
1
2
3
4
5
6
7
|
---
title: "Hello Hugo"
date: 2025-04-04
draft: false
---
This is my first post! I'm still learning Hugo
|
Preview the site locally & build the public/ folder
1
2
3
4
|
# Enter in the current root directory
hugo server -D
# Open the browser to see the result
http://localhost:1313
|
When you want to deploy your site, run:
This command will generate a public/ folder, which contains the static web page content that has been built and can be deployed directly. The content you deploy to the web page should be under public/
1
2
3
4
5
6
7
8
9
|
# Enter the public/ directory and initialize Git.
cd public
git init
git remote add origin https://github.com/yourusername/yourusername.github.io.git
git checkout -b gh-pages
# Commit the build and push it to the gh-pages branch.
git add .
git commit -m "Manually deploy Hugo Pages"
git push -f origin gh-pages
|
- Set up a Pages branch on GitHub.
- Open your GitHub repository.
- Click Settings → Pages on the menu bar.
- In the Source section, select:
- Branch: gh-pages
- Directory: / (root)
- Save and wait for GitHub to automatically generate the page (this should take a few minutes).
Deploy to GitHub Pages (automatically deploy using Actions)
Initialize Git and push to GitHub
1
2
3
4
5
6
7
|
# In the root directory
git init
git add .
git commit -m "first commit"
git branch -M main
git remote add origin git@github.com:yourusername/yourusername.github.io.git
git push -u origin main
|
If you’re using HTTPS, change git@github.com… to https://github.com/yourusername/yourusername.github.io.git
Add a deployment workflow
- Create the file .github/workflows/deploy.yml (in the root directory): (Note that the .github folder is also created by you)
- Copy the following content into deploy.yml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
|
Name: Deploy Hugo site to GitHub Pages
On:
Push:
Branches:
-main # Automatically deploy every time you push to the main branch
Jobs:
Build:
Runs-on: ubuntu-latest
Steps:
-Name: Checkout code
Uses: actions/checkout@v4
-Name: Setup Hugo
Uses: peaceiris/actions-hugo@v2
With:
Hugo-version: 'latest'
Extended: true
-Name: Build Hugo site
Run: hugo --minify
-Name: Deploy to GitHub Pages
Uses: peaceiris/actions-gh-pages@v3
With:
GitHub_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./public
|
Summary
Whenever you want to write new content, just:
1
2
3
4
5
6
7
8
9
10
11
12
|
# Store the file in the content directory
hugo new <your file path>
# View locally
hugo server -D
# View in a browser
http://localhost:1313
# Then, go directly to the root directory. Note that your current branch should be main
## View branches
git branch
git add .
git commit -m "your log"
git push origin main
|
From now on, the deploy.yml file you create will automatically deploy the web page under actions, eliminating the need to push the static web page again to the public directory. Your web page source code is in the main branch, and the statically deployed web page code is in the public folder (which is also where you can access your web page code).
Automatic Commit Script (Optional)
If you want to skip the git add . process, here’s a Python script reference.
1
2
3
4
5
6
7
8
9
10
|
# Create auto_push.py in the current root directory
import subprocess
from datetime import datetime
def auto_push():
now = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
msg = f"update: {now}"
subprocess.run(["git", "add", "."], check=True)
subprocess.run(["git", "commit", "-m", msg], check=True)
subprocess.run(["git", "push", "origin", "main"], check=True)
auto_push()
|
To run:
Congratulations!
You’ve successfully created and deployed your own blog using Hugo and GitHub Pages on Windows!
