Preface#
Hugo is a static site generator written in Go, which is very suitable for blogging. Let's get started!
Download the Program#
git.exe // Installation
hugo.exe // No installation required, just place it in a suitable location
Configure Environment Variables#
Open This PC - Right-click Properties - Advanced System Settings - Advanced Environment Variables - System Variables - Select path - Edit - New Environment Variable - "Enter the folder path where Hugo is located" - Confirm
Remember to run CMD and execute hugo -version to check if it is configured correctly.
Create a Blog#
Enter the hugoblog folder, right-click and select Open Git Bash here.
Paste the following code one by one into the black window to execute:
hugo new site hugoblog // Create a project named hugoblog hugo new site hugoworks
cd hugoblog // Enter hugoblog
hugo new about.md // Create an about page, you can write something casually, or leave it blank
Download Themes#
- Download your favorite theme (available on the official website) and place it in the hugoblog/themes folder. I will download papermod; the theme projects are all on GitHub, find the project and clone it down.
git clone https://github.com/nanxiaobei/hugo-paper.git
- Copy the entire exampleSite to the hugoblog directory and rename config.toml to hugo.toml. If prompted about overwriting a file with the same name, confirm.
View the Blog#
In the hugoblog folder, right-click and select Open Git Bash here.
hugo server --theme=blist --buildDrafts # Debug by replacing the theme name
Then the black window will give you an address. Open it by right-clicking and selecting open, or open it in a browser: http://localhost:1313/. If everything goes well, you will see a page that looks like the demo page of the official theme.
If something goes wrong, check here:
Possible Issues
Configure the Theme#
Change some elements of the page to your desired appearance.
Open hugo.toml with Notepad or any text editor.
The items marked with ### must be modified; you can refer to my changes. Others can be modified or left unchanged.
The page displays in real-time, so once you modify it here, you can see the effect in the browser.
baseURL = "https://junxinjay.github.io" # Page address
# title = "君心的博客"
author = "君心jay"
copyright = "Copyright © 2008–2024, Steve Francia and the lee.so; all rights reserved."
paginate = 5 # Number of pages
languageCode = "zh"
DefaultContentLanguage = "zh"
enableInlineShortcodes = true
# prevent build failures when using Hugo's Instagram shortcode due to deprecated Instagram API.
# See https://github.com/gohugoio/hugo/issues/7228#issuecomment-714490456
ignoreErrors = ["error-remote-getjson"]
# ------------------------------
theme = "paper"
title = "君心Jay"
[params]
# color style
color = 'gray' # linen, wheat, gray, light
logo = "/apple-touch-icon.png"
twitter = 'Jay80820750'
qq = 'q/ki1zhngt6E'
rss = true # show rss icon
# ------------------------------
# needed to render raw HTML (e.g. <sub>, <sup>, <kbd>, <mark>)
[markup]
[markup.goldmark]
[markup.goldmark.renderer]
unsafe = true
[menu]
[[menu.main]]
identifier = "blog"
name = "Articles"
url = "/blog/"
weight = 1
[[menu.main]]
identifier = "about"
name = "About"
url = "/about/"
weight = 2
[[menu.main]]
identifier = "contact"
name = "Friend Links"
url = "/contact/"
weight = 3
[[menu.main]]
identifier = "search"
name = "Search"
url = "/search/"
weight = 4
[taxonomies]
category = "categories"
tag = "tags"
series = "series"
[privacy]
[privacy.vimeo]
disabled = false
simple = true
[privacy.twitter]
disabled = false
enableDNT = true
simple = true
[privacy.instagram]
disabled = false
simple = true
[privacy.youtube]
disabled = false
simple = true
[privacy.qq]
disabled = false
simple = true
[privacy.WeChat]
disabled = false
simple = true
[privacy.bilibili]
disabled = false
simple = true
[services]
[services.instagram]
disableInlineCSS = true
[services.twitter]
disableInlineCSS = true
Modify the Theme (This step can be skipped)#
The static folder under the theme contains images used by the theme, which can be modified as needed.
The layouts folder under the theme is the entire theme framework page; beginners should avoid modifying it, or else the page may throw errors.
Write a Blog#
Blogs are written using a Markdown editor, but you can also use txt if you are familiar with Markdown syntax. I recommend using Typora for writing articles, but you can choose other editors as well.
Once written, place everything in the post directory under the content folder. Images referenced in articles should be placed in the static directory.
Generate Static Page Files#
Every time you finish writing a blog, you need to regenerate the static pages by executing the following in the hugoblog directory:
hugo -F --cleanDestinationDir
After execution, the generated files will be in the public folder.
Deploy to GitHub#
⚠️ It is not recommended to deploy to Gitee due to slow review processes, and often the pages become unusable shortly after deployment, with strict review policies.
• Deploy to GitHub#
⚠️ If you don't have GitHub, first register an account.
-
Open GitHub, create a project, click New repository, fill in your username for Repository name (this step is very important), leave the rest blank, click Create repository, and remember the repository address for later use.
-
Enter the public directory, right-click and select Open Git Bash here.
Execute the following line by line:
cd public
git init # Use this the first time; for subsequent blog updates, you won't need it.
#git remote add origin https://github.com/junxinjay/hugo.git # Replace with your repository address; use this the first time; for subsequent blog updates, you won't need it.
#git remote # Use this the first time; for subsequent blog updates, you won't need it.
git add . // Add all files to the staging area
git status // Check status
git commit -m 'MyFirstCommit' // Commit files to the repository -m is the message
#git push -u origin master # Use this the first time; for subsequent blog updates, just use git push.
Here I use GitHub Desktop to push.
Download the GitHub Desktop software from https://desktop.github.com, log in after installation, and when prompted with Let's get started!, choose add an Existing Repository from your local drive... select the public folder, and click Fetch origin to push.
-
At this point, you can open https://github.com/junxinjay/blog.io to see the page. Due to slow access to GitHub from within China, we will also use Netlify for one-click hosting.
-
Open the GitHub project settings, select Pages, and in the branch section, select master to save.
-
Open Netlify and log in using GitHub.
Possible Issues#
• Possible Issues#
Error: error building site: POSTCSS: failed to transform "/css/styles.css" (text/css). Check your PostCSS installation; install with "npm install postcss-cli". See https://gohugo.io/hugo-pipes/postcss/: binary with name "npx" not found
You need to install Node.js. Go to the official website to download and install it.
Just install it, and if it still doesn't work, execute:
npm install
npm i -g postcss-cli
• Possible status failure#
On branch main
Your branch is ahead of 'origin/main' by 1 commit.
(use "git push" to publish your local commits)
nothing to commit, working tree clean
Execute:
git push origin master
Or:
git reset
git clean -f
git checkout -- .
• Possible push failure#
$ git push
fatal: unable to access 'https://github.com/junxinjay/hugoblog.github.io.git/':
Failed to connect to github.com port 443 after 2081 ms: Couldn't connect to server
Get the IP from the website:
https://sites.ipaddress.com/www.github.com/
Add the IP and github.com to your hosts file:
140.82.112.4 github.com
Then try pushing again.
• Possible issues#
$ git status
On branch master
Your branch is ahead of 'origin/master' by 1 commit.
(use "git push" to publish your local commits)
nothing to commit, working tree clean
Execute:
git fetch
Then git push.
• Possible issues#
fatal: detected dubious ownership in repository at 'D:/Software/12code/hugo/myblog/public'
'D:/Software/12code/hugo/myblog/public' is owned by:
'S-1-5-32-544'
but the current user is:
'S-1-5-21-3826342517-2274634027-510025631-1001'
To add an exception for this directory, call:
git config --global --add safe.directory D:/Software/12code/hugo/hugoblog/public
Execute:
git config --global --add safe.directory "*";
• Possible issues#
Author identity unknown
*** Please tell me who you are.
Run
git config --global user.email "[email protected]"
git config --global user.name "Your Name"
to set your account's default identity.
Omit --global to set the identity only in this repository.
fatal: unable to auto-detect email address (got 'Jay@DESKTOP.(none)')
Execute:
git config --global user.email "your email"
git config --global user.name "your name"
Invalid string binding:
git config --system --unset credential.helper
• Possible issues#
fatal: unable to access 'https://gitclone.com/github.com/XXXXXXX': The requested URL returned error: 502
Add a # in front of these two lines in the C:\Users\username.gitconfig file:
[url "https://gitclone.com/"]
[url "https://github.com/"]
• Possible issues#
remote: Support for password authentication was removed on August 13, 2021.
remote: Please see https://docs.github.com/get-started/getting-started-with-git/about-remote-repositories#cloning-with-https-urls for information on currently recommended modes of authentication.
fatal: Authentication failed for 'https://github.com/junxinjay/hugoblog.github.io.git/'
This means: Your previous password credential has been invalid since August 13, 2021, and you must use a personal access token instead of your password!
Open GitHub - Settings - Developer Settings.
• Possible issues#
fatal: unable to access 'https://github.com/test/test.git/': schannel: failed to receive handshake, SSL/TLS connection failed
Modify D:[Application Data Directory]\Documents\GitHub\test.git
[core]
repositoryformatversion = 0
filemode = false
bare = false
logallrefupdates = true
symlinks = false
ignorecase = true
[submodule]
active = .
[remote "origin"]
url = https://github.com/test/test.git
fetch = +refs/heads/*:refs/remotes/origin/*
[branch "main"]
remote = origin
merge = refs/heads/main
# Add the following section and save
[http]
sslbackend = openssl
• Possible issues#
Failed to find a valid digest in the 'integrity' attribute for resource - The resource has been blocked - Host on Github
Add the following to the config file in git:
params:
assets:
disableFingerprinting: true
• Possible issues#
Failed to connect to github.com port 443 after 21480 ms: Couldn't connect to server
Use a VPN to push again.