Huangh's blog

本站是如何构建的

Posted on May 21, 2024

碎碎念

这个博客是我在很久以前就是开始维护了，最初使用的是 Hugo 生成的静态内容并托管在 GitHub Pages 上，长期使用过两个大而全的主题，可见多了容易审美疲劳，于是就准备走向“大道至简”；由于近期在学习 Rust，被系统推荐到另一个静态站点生成器 Zola，于是就尝试了一下从 Hugo 迁移到 Zola，但是令我沮丧的不仅是 Zola 的主题生态不如 Hugo，而是 Zola 作者没有计划支持自定义 URL 模板或者添加一个选项以将日期集成到路径中没那么快实现；显然本站的博文 URL 是包含日期的，暂无精力处理这个迁移问题，于是就又回到了 Hugo。

工作流

好的工作流可以确保博客开发和部署的高效和可维护性，使得开发者可以专注于内容创作而不是复杂的部署过程。

my-blog-workflow

  • 🟢 localhost 表示本地开发环境。
    • 在本地计算机上，使用 Hugo 生成和预览博客内容。
    • 通过 Hugo 的本地服务器查看和调试博客，确保所有内容和样式都正确显示。
  • 🟡 https://github.com/<username>/<username>.github.io 表示 GitHub Pages 仓库。
    • 这是用于 GitHub Pages 部署的仓库。通常它的名字为 <username>.github.io，其中 <username> 是 GitHub 用户名，例如 https://github.com/h2cone/h2cone.github.io
    • 从博客主仓库部署（deploying）生成的静态文件到这个仓库。可以通过 git submodule 或 gh-pages 分支来支持。
    • 部署后，GitHub Pages 服务会自动从这个仓库中提取内容，并在 URL https://<username>.github.io 上提供服务（serving）。
  • 🟣 https://github.com/<username>/<blog> 表示博客主仓库。
    • 博客的主要源代码托管在 GitHub 仓库中。这个仓库包含所有博客文章、配置文件和 Hugo 所需的其他资源。若无权访问则可能是因为作者将其设置为私有仓库，例如 https://github.com/h2cone/blog
    • 本地开发完成后，将修改内容同步（syncing）到这个仓库。通过 git push 命令将本地更改推送到 GitHub 仓库。
  • 🔵 https://github.com/<username>/<theme> 表示主题仓库。
    • 博客使用的主题托管在另一个 GitHub 仓库中，例如 https://github.com/h2cone/archie
    • 博客主仓库通过引用（reference to）这个主题仓库来应用特定的样式和布局。Hugo 使用主题仓库中的文件来生成博客的外观。
  • 🔴 https://<username>.github.io 表示博客站点。
    • 这是实际对外展示的博客网站。用户可以通过这个 URL 访问部署在 GitHub Pages 上的博客，例如 https://h2cone.github.io
    • 这个网站由 GitHub Pages 服务托管，内容来自于 GitHub Pages 仓库。

关键步骤

  1. 在本地通过 Hugo 新建项目，我的主仓库目录如下所示：
~/projc/blog$ tree -a -L 1
.
├── archetypes
├── assets
├── backup.sh
├── config.toml
├── content
├── data
├── deploy.sh
├── .git
├── .gitignore
├── .gitmodules
├── .hugo_build.lock
├── layouts
├── LICENSE
├── public
├── README.md
├── resources
├── static
└── themes

Windows 用户推荐使用 WSL，可以在 Windows 上安装 Linux 子系统，然后在子系统中安装 Hugo，这样可以减少一些部署或跨平台同步障碍。

  1. 从 Hugo 官方主题库选择一个你喜欢的主题，看看主题的文档了解如何使用它，一般都要复制一些文件到你的主仓库中，然后在 config.toml 中配置主题，这里使用的主题叫做 archie。
~/projc/blog$ tree -a -L 1 themes/
themes/
├── archie
└── .gitkeep

个人认为最佳实践是将主题作为 Git 子模块添加到主仓库中，这样可以方便管理主题版本，也可以保持主题和博客的分离。

~/projc/blog$ cat .gitmodules
[submodule "themes/archie"]
        path = themes/archie
        url = https://github.com/h2cone/archie.git
        branch = master

可能会好奇为什么 Fork 了主题仓库，这是因为我想要魔改主题，但是又不想受到主题作者的更新影响，所以 Fork 了一个副本，然后在副本上进行修改。

  1. 本地开发完成后，通过 hugo server 命令启动本地服务器，添加博文，查看博客效果，这里的博文全放入 content/post 目录下，每篇博文都有一个单独的目录，目录名就是博文的 URL，例如 content/post/2024/05/21/build_this_site.md
~/projc/blog$ tree -a content/post/2024
content/post/2024
├── 01
│   └── 31
│       └── your-own-chrome-extension.md
└── 05
    └── 21
        └── build_this_site.md

感觉 URL 太长了，可以通过修改 config.toml 中的 permalinks 配置来简化 URL，例如：

[permalinks]
  post = '/:year/:month/:day/:filename/'

访问博文的 URL 就变成了 2024/05/21/build_this_site，这样看起来更简洁。

  1. 本地开发完成后，通过 hugo -t 命令生成静态文件到目录 public，然后通过 deploy.sh 脚本将生成的静态文件发布到 GitHub Pages 仓库中，这个脚本的内容如下：
#!/bin/sh

# If a command fails then the deploy stops
set -e

printf "\033[0;32mDeploying updates to GitHub...\033[0m\n"

# Go to public
cd public
git checkout master
git pull origin master

# Go to root
cd ..

# Build the project
hugo -t archie

# Add changes to git
cd public
git add .

# Commit changes
msg="rebuilding site $(date)"
if [ -n "$*" ]; then
	msg="$*"
fi
git commit -m "$msg" --allow-empty

# Push source and build repos
git push origin master

前提是你先在 GitHub 创建了 GitHub Pages 仓库，将 public 添加为主仓库的子模块，这里主仓库总共引用了两个子模块：

~/projc/blog$ cat .gitmodules
[submodule "themes/archie"]
        path = themes/archie
        url = https://github.com/h2cone/archie.git
        branch = master
[submodule "public"]
        path = public
        url = git@github.com:h2cone/h2cone.github.io.git
        branch = master

  1. 查看 GitHub Pages 仓库是否正常触发 pages build and deployment 运行，如果类似的 GitHub Actions 运行成功，比如 https://github.com/h2cone/h2cone.github.io/actions，那么就可以通过 https://<username>.github.io 访问你的博客了。

  2. 备份博客内容，这里我使用了一个简单的脚本 backup.sh，将博客主仓库推到 GitHub，这样即使本地丢失了博客内容，也可以通过 GitHub 仓库恢复。

#!/bin/sh

git add .

msg="$(date)"
if [ -n "$*" ]; then
	msg="$*"
fi
git commit -m "$msg" --allow-empty

git push -v

遇到的一些坑

  • WSL 处理非 /home 项目性能较差？嫌 Hugo 构建太慢因此将项目移动到 /home 目录下。
  • 在我的另外一台笔记本电脑上 git clone git@github.com:h2cone/blog.git 到本地时运行 hugo server 看到一片空白，原来是手势不对，没有初始化子模块，导致主题没有下载下来，解决方法：
  1. git submodule init
  2. rm -rI public/ themes/
  3. git submodule update
  • 遇到 error: RPC failed; curl 92 HTTP/2 stream 0 was not closed cleanly: CANCEL (err 8)
    • 直接降级 git config –global http.version HTTP/1.1

总结

这篇文章主要介绍了我是如何构建这个博客的，希望对你有所帮助，如果你有任何问题或建议，欢迎在下面留言，谢谢！

本文首发于 https://h2cone.github.io/

参考