博客搭建记录
1. 环境准备
1.1 go环境
安装：官网https://go.dev/doc/install直接下载msi安装包安装即可
校验：go version
1.2 hugo
CMD命令行直接安装：winget install Hugo.Hugo.Extended
校验：hugo version
1.3 git
安装：略
校验：git --version
1.4 github
创建两个仓库，除了权限，先什么都不要设置。
仓库1：https://github.com/imhaozi/blog，权限私有，存放原文档
仓库2：https://github.com/imhaozi/imhaozi.github.io，权限公开，存放静态页面
2. 本地搭建
2.1 创建项目
创建 Hugo 项目。
在CMD窗口中任意目录下，运行hugo new site blog --format yaml，运行后，会自动创建blog文件夹
G:\>hugo new site blog --format yaml
Congratulations! Your new Hugo project was created in G:\blog.
Just a few more steps...
1. Change the current directory to G:\blog.
2. Create or install a theme:
- Create a new theme with the command "hugo new theme <THEMENAME>"
- Or, install a theme from https://themes.gohugo.io/
3. Edit hugo.yaml, setting the "theme" property to the theme name.
4. Create new content with the command "hugo new content <SECTIONNAME>\<FILENAME>.<FORMAT>".
5. Start the embedded web server with the command "hugo server --buildDrafts".
See documentation at https://gohugo.io/.
G:\>cd blog
G:\blog>git init
Initialized empty Git repository in G:/blog/.git/初始化 Hugo Module：hugo mod init github.com/imhaozi/blog
G:\blog>hugo mod init github.com/imhaozi/blog
go: creating new go.mod: module github.com/imhaozi/blog
hugo: to add module requirements and sums:
hugo mod tidy安装 Hextra：hugo mod get github.com/imfing/hextra
G:\blog>hugo mod get github.com/imfing/hextra
go: added github.com/imfing/hextra v0.12.32.2 添加内容
内容配置。修改blog/hugo.yaml，后续还可以自己美化修改。
这里添加两个栏目，分别是blog和project
baseURL: "https://imhaozi.github.io/"
languageCode: zh-cn
title: imhaozi 的博客
module:
imports:
- path: github.com/imfing/hextra
menu:
main:
- name: 博客
pageRef: /blog
weight: 1
- name: 项目
pageRef: /project
weight: 2
- name: 搜索
weight: 3
params:
type: search
params:
theme:
default: system
displayToggle: true
markup:
highlight:
noClasses: false创建内容，blog/content路径下添加内容
- 创建blog、project文件夹，分别对应上面两个栏目
- blog/content目录下、blog/content\blog目录下、blog/content/project目录下，分别创建文件**_index.md**
内容如下（可以写的不一样，用于区分）：
---
title: XX
---
欢迎来到我的XX。源码仓库不存放静态页面，因此在根目录blog下添加**.gitignore**文件
public/
resources/_gen/
.hugo_build.lock
.DS_Store这样的效果：源码仓库不提交**public/**目录。
2.3 本地预览
CMD执行：hugo server --buildDrafts --disableFastRender
浏览器即可访问弹出的地址：http://localhost:1313/
3. 自动化发布
因为 Actions 在私有仓库 imhaozi/blog 里运行，但要写入另一个公开仓库 imhaozi/imhaozi.github.io，所以需要一个 token。GITHUB_TOKEN 常用于当前仓库内的自动化操作；跨仓库写入时，使用单独的 secret/token 更合适，并且应授予最小必要权限。
3.1 生成token
在 GitHub 页面找到如下设置：
个人头像
→ Settings
→ Developer settings
→ Personal access tokens
→ Fine-grained tokens
→ Generate new token这样设置：
Token name: deploy-blog-to-pages
Expiration: 建议选 90 days / 1 year
Repository access: Only select repositories
Selected repository: imhaozi/imhaozi.github.io
Permissions: 添加Contents，然后改成Read and write，Metadata默认只读，不用管生成后复制 token。
3.2 添加token
进入私有仓库：
imhaozi/blog然后进入：
Settings
→ Secrets and variables
→ Actions
→ New repository secret添加：
Name: PAGES_REPO_TOKEN
Value: 刚才复制的 token注意名字必须完全一致：
PAGES_REPO_TOKEN3.3 创建 Actions 工作流
在本地项目根目录创建如下路径和文件blog/.github/workflows/deploy.yaml
mkdir .github
mkdir .github\workflows
notepad .github\workflows\deploy.yaml写入下面内容：
name: Build Hugo and deploy to GitHub Pages repo
on:
push:
branches:
- main
workflow_dispatch:
permissions:
contents: read
concurrency:
group: deploy-blog
cancel-in-progress: false
jobs:
build-and-deploy:
runs-on: ubuntu-latest
env:
HUGO_VERSION: 0.161.1
steps:
- name: Checkout source
uses: actions/checkout@v6
with:
fetch-depth: 0
- name: Setup Go
uses: actions/setup-go@v6
with:
go-version: stable
- name: Install Hugo Extended
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: Build Hugo site
env:
HUGO_ENVIRONMENT: production
HUGO_ENV: production
run: |
hugo --gc --minify --baseURL "https://imhaozi.github.io/"
- name: Add .nojekyll
run: |
touch public/.nojekyll
- name: Deploy public folder to imhaozi.github.io
env:
PAGES_REPO_TOKEN: ${{ secrets.PAGES_REPO_TOKEN }}
run: |
cd public
git init
git config user.name "github-actions[bot]"
git config user.email "github-actions[bot]@users.noreply.github.com"
git add .
git commit -m "deploy site from imhaozi/blog@${{ github.sha }}"
git branch -M main
git remote add origin https://x-access-token:${PAGES_REPO_TOKEN}@github.com/imhaozi/imhaozi.github.io.git
git push -f origin mainactions/checkout@v6 和 actions/setup-go@v6 是当前可用的官方 Actions 版本；setup-go 用来在工作流里安装 Go 环境。
3.4 推送到远端
提交源码：
git add .
git commit -m "init hugo hextra blog source"
git branch -M main绑定远程私有仓库：
git remote add origin https://github.com/imhaozi/blog.git推送：
git push -u origin main推送完成后，进入私有仓库的：
Actions你应该能看到：
Build Hugo and deploy to GitHub Pages repo等待它运行成功。公开仓库就会有静态页面发布了，并且https://imhaozi.github.io/已经可以访问了。
如果没有，大概率blog/.github/workflows/deploy.yaml中有配置项不匹配，主要是分支名和仓库名
然后进入公开仓库：
imhaozi/imhaozi.github.io如果 Actions 已经成功运行一次，这个仓库里应该已经出现：
index.html
blog/
.nojekyll
...然后进入：
Settings
→ Pages设置为：
Build and deployment
→ Source: Deploy from a branch
→ Branch: main
→ Folder: / root
→ SaveGitHub Pages 支持把某个分支的根目录作为发布源；每当这个分支收到更新，Pages 就会发布该目录中的静态内容。
如果刚进入 Pages 设置时看不到 main 分支，说明 imhaozi.github.io 还是空仓库。先等 imhaozi/blog 的 Actions 成功跑完，再回来设置。
4. 内容新增
以后只维护私有仓库 imhaozi/blog。
本地进入项目：
git pull新建文章：
hugo new content blog\new-post.md本地预览：
hugo server --buildDrafts --disableFastRender写完后提交：
git add .
git commit -m "add new post"
git push之后自动发生：
push 到 imhaozi/blog
→ GitHub Actions 构建 Hugo
→ 生成 public/
→ 推送到 imhaozi/imhaozi.github.io
→ GitHub Pages 更新5. 补充
有时候直接下markdown其实不是很方便，尤其是图片多的时候。
可以先用word文档编写，写完之后使用工具转成markdown，然后稍微调整一下即可。
Typora设置中有说到pandoc工具，安装完之后，直接在windows命令行中输入以下指令即可。
pandoc test.docx --extract-media=./images -o test.md注意：
- word中的标题从二级标题开始，这样转换的md文件不用调整标题格式
- 转换的md文件中图片路径会多一层目录，可以全局替换即可