简介
#

本文记录用 Github Pages + Hugo + Blowfish 搭建博客的重要事项. 大部分内容参考自网络上的博客, 以及 Hugo 和 Blowfish 的官方文档、教程.

安装环境
#

我使用的是 Windows 11 系统, 使用 Powershell 7.5.2.

第一步要安装 Git 和 Hugo. Windows 现在提供了命令行工具 WinGet, 用它来安装软件包非常方便, 特别是可以免去「添加到 PATH」这一步. 和 linux 一样, 安装的指令往往都可以在软件官网直接找到, 例如安装 Git for Windows 的指令是

winget install --id Git.Git -e --source winget

安装 Hugo 的指令是

winget install Hugo.Hugo.Extended

如此安装后, Hugo 会自动添加到 PATH 里, 所以可以直接用

hugo version

检查是否安装成功.

创建本地站点
#

在 Powershell 中, 输入

hugo new site <site-name>

可以新建一个 Hugo 项目, 文件结构如下:

<site-name>
├─archetypes
├─assets
├─content
├─data
├─i18n
├─layouts
├─static
└─themes

接下来需要安装主题. 我采用的是 Blowfish 主题, 安装命令是

cd mywebsite
git init -b main
git submodule add -b main https://github.com/nunocoracao/blowfish.git themes/blowfish

安装后, Blowfish 主题文件会存放在 theme 文件夹下.

<site-name>
├─archetypes
├─assets
├─content
├─data
├─i18n
├─layouts
├─static
└─themes
    └─blowfish
        ├─archetypes
        ├─assets
        │  ├─...
        ├─config
        │  └─_default
        ├─data
        ├─exampleSite
        │  ├─...
        ├─i18n
        ├─images
        ├─layouts
        │  ├─...
        ├─release-versions
        └─static

其中 exampleSite 是 Blowfish 官网同款网站, 可以用来体验和学习.

接下来需要把 themes\blowfish\config 移动到 <site-name> 目录下, 并删除 <site-name> 目录下原来的 hugo.toml 文件, 用 Blowfish 主题的配置代替默认主题. 然后可以复制 theme\blowfish\archetypes 中的文件, 替换 <site-name>\archetypes 中的文件. 这些 md 文件是模板, 创建新页面时会用到.

接下来打开 config\_default\hugo.toml, 在开头会看到

# -- Site Configuration --
# Refer to the theme docs for more details about each of these parameters.
# https://blowfish.page/docs/getting-started/

# theme = "blowfish" # UNCOMMENT THIS LINE
# baseURL = "https://your_domain.com/"
defaultContentLanguage = "en"

把 theme = ... 和 baseURL = ... 取消注释. 前者会应用 Blowfish 主题, 后者则是网站的 url, 如果是用 Github Pages, 可以改成对应的 url, 即 https://<github-username>.github.io.

至此就可以测试网站了, 在 <site-name> 目录下运行

hugo server

运行后命令行中会显示

...
Environment: "development"
Serving pages from disk
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop

用其中给出的 http://localhost:1313/ 即可预览. 按 Ctrl+C 停止预览. 此外, 这个预览会实时更新, 即若改变了本地文件, 网页会自动刷新并更新, 同时, 如果本地文件中出现了错误, 那么预览处也能看到哪里有问题.

站点配置
#

待续

发布
#

Github Page 是静态网页托管平台, 所以需要先用 Hugo 生成静态网站, 再推送到 Github 仓库.

首先在 <site-name> 目录下执行

hugo

生成静态网站. 其会生成在 <site-name>\public 文件夹下. 接下来只需要上传此文件夹即可. 即

cd public
git init -b main
git remote add origin <your repo.git here>
git pull --rebase origin main

从远程仓库拉取, 再

git add .

添加本体所有文件. 如果这一步 git 有警告(warning), 提示内容是 ... LF will be replaced by CRLF ..., 则需要特殊处理一下. 具体原理和处理方案可见此处. 简单来说就是 Windows 和 Unix 换行处理不同, 导致某个 SHA256 属性不匹配. 解决方案就是先执行(只需执行一次, 会永久改变)

git config --global core.autocrlf false

清理掉之前生成的 public 内容, 重新执行上述 Hugo 和 Git 操作. git add . 之后, 就可以推送到远程了

git commit -m "[your comment here]"
git push origin main

至此, 可以在 https://<github-username>.github.io 看到博客了(可能需要等几秒钟才会生效). 之后添加了内容之后, 用 Git 推送即可.

参考资料
#

Hugo Documentation

Blowfish 中文文档

如何使用 Github Page 搭建自己的博客

解决Hugo无法加载css文件

简介 #

安装环境 #

创建本地站点 #

站点配置 #

发布 #

参考资料 #