本系列教程为你展示搭建个人博客的技巧, 分为三个部分:

• pt.1 - 创建本地博客网站项目 (本文)
  • 使用 Hugo 构建静态博客.
• pt.2 - 同步静态博客至 QNAP NAS
  • 使用 Qsync 从本地将静态博客同步至 QNAP NAS 上专属虚拟主机目录下.
• pt.3 - 同步静态博客至 Backblaze B2 和 Cloudflare
  • 使用 HBS 3 (Hybrid Backup Sync 3) 从 QNAP NAS 将静态博客同步至 Backblaze B2, 并设置 Cloudflare 加速.

创建 Github 远程 Repo

本教程使用 Github 同步/备份所创建的博客网站项目, 因此需要先创建它对应的 Github 远程 Repo.

注意:

为行文方便, 本教程以 blog.zhaijia.fun 作为示例的静态博客域名和 Repo 名.

请勿照抄, 务必将其替换为你自己的域名!

你必须要有一个 Github 账号, 如果没有, 点击此处免费注册.

登录 Github 后, 进入此处创建新的 Repo.

这里将此 Repo 的类型设置为 “Private” (私有的), 意为其中存放的目录/文件只对你自己可见.

如果将来需要部署至某些要求 Repo 必须是 “Public” 的静态网站托管服务, 比如 Netlify, 请修改为 “Public”.

安装 Hugo

进入此处查看并下载最新版本的 Hugo.

如果你的本地系统是 macOS, 可按照下面的简洁方式快速安装 Hugo:

1
2
3
4
5
6
7
8
9

#### 安装
brew install hugo

#### 查看版本
hugo version

例如:

hugo v0.97.3+extended darwin/amd64 BuildDate=unknown

注意: 必须是扩展版本的 Hugo, 即: extended

创建博客网站项目

1
2
3
4
5
6
7
8

#### 在某个指定的目录下执行:
hugo new site blog.zhaijia.fun

#### 进入对应的博客网站项目目录
cd blog.zhaijia.fun

#### git 初始化
git init

安装主题

请查看此处或自行搜索你喜欢的主题, 然后按照相关的说明文档安装并配置.

安装 Stack 主题

这里选择安装 Stack 主题:

1
2
3
4
5
6
7
8
9

#### 以子模块的方式安装
git submodule add https://github.com/CaiJimmy/hugo-theme-stack/ themes/hugo-theme-stack

#### 使用样例配置作为开始, 以后可在此基础上再次按需修改
cp themes/hugo-theme-stack/exampleSite/config.yaml .
cp -R themes/hugo-theme-stack/exampleSite/content .

#### 删除默认的配置文件 config.toml, 因为已经有了 config.yaml
rm config.toml

基本配置

网站配置 config.yaml

忽略某些目录/文件

这里创建 .gitignore, 在其中放入不需要同步至 Github 的目录/文件, 例如:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

#### .gitignore

#### lock for building
/.hugo_build.lock

#### public 是 Hugo 构建静态网站的默认发布目录.
/public/

#### Hugo 资源目录
/resources/

#### 图片, 视频, 音频等体积较大的文件, 仅限目录 /content/post/**
/content/post/**/*.jpg
/content/post/**/*.jpeg
/content/post/**/*.png
/content/post/**/*.gif
/content/post/**/*.webp

/content/post/**/*.mp4
/content/post/**/*.mov

/content/post/**/*.mp3
/content/post/**/*.m4a

#### 任意的 .DS_Store (macOS)
**/.DS_Store

此示例意为在同步至 Github 时, 将 Hugo 构建静态网站的默认发布目录 public, Hugo 资源目录, 文章所引用的图片, 视频, 音频等体积较大的文件和任意的 macOS 保存目录自定义属性的隐藏文件 .DS_Store 排除在外.

启动本地博客网站 (Hugo 调试环境)

1

hugo server -D --disableFastRender --noHTTPCache

如果一切正常, 去浏览器查看本地博客网站: http://localhost:1313/.

• -D 意为也对标记为草稿的文章生成页面.
• 由于本主题使用了 Hugo 中的 .Scratch 来实现一些特性, 非常建议你为 hugo server 命令添加 –disableFastRender 参数来实时预览你正在编辑的文章页面.
• --noHTTPCache 意为阻止服务器端的缓存, 总是向浏览器发送内容而不是提示内容已最新 (HTTP 304). 按下 Ctrl + C 退出 Hugo 调试环境.

如果需要带域名启动, 只需添加参数 –baseURL, 例如:

1

hugo server -D --disableFastRender --noHTTPCache --baseURL http://blog.zhaijia.fun

将会提示: Web Server is available at http://blog.zhaijia.fun:1313/ (bind address 127.0.0.1)

此时需将域名 blog.zhaijia.fun 本地解析到 127.0.0.1 才能在浏览器中正常访问上面的地址.

首次同步至 Github 远程 Repo

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

#### 配置连接 Github 时的账户信息 ####
#### 配置默认账户,即多个 Repo 共享的 Github 账户
git config --global user.email "your-email"
git config --global user.name "your-user-name"

#### 配置仅用于连接当前 Repo 的 Github 账户
git config user.email "your-email"
git config user.name "your-user-name"

#### 添加当前目录下的所有目录/文件
git add .

#### 提交并进行注释
git commit -m "首次提交"

#### 切换至主分支 (main)
git branch -M main

#### 链接到远程 Repo
git remote add origin https://github.com/your-user-name/blog.zhaijia.fun.git

#### 同步本地的目录/文件至 Github
git push -u origin main

配置连接 Github 时的账户信息, 有两种情况:

• 你只有一个 Github 账户, 则使用带 –global 的版本.
• 你有多个 Github 账户, 则使用不带 –global 的版本.

请替换 your-email 为你自己的 Github 账户邮箱.

请替换 your-user-name 为你自己的 Github 账户用户名.

提示输入密码时, 请输入你的 personal access token 而非 github 账户密码, 此规定已于 2021-8-13 启用, 详见: https://github.blog/2020-12-15-token-authentication-requirements-for-git-operations/

请查看此处来生成一个 personal access token.

至此, 你的博客网站项目已经创建完毕并可随时同步至 Github (通过 git 命令).

进阶配置

网站配置 config.yaml

网站域名 baseurl

例如: baseurl: “https://blog.zhaijia.fun”

网站名称

title: 快乐宅家

首页显示的文章数 paginate

设置为简体中文

• languageCode: zh-cn
• DefaultContentLanguage: zh-cn
• hasCJKLanguage: true
• 注释掉 languages 以取消多语言设置

网站图标 params.favicon

请把 favicon.ico 放在网站根目录的 static 文件夹下, 这里填写 /favicon.ico .

左侧边栏 params.sidebar

emoji

头像底部的 Emoji, 留空不显示.

网站介绍 subtitle

subtitle: 非常用心地随便写

头像 avatar

• enabled: true 显示头像.
• local: true 使用本地头像文件.
• src:
  • 本地头像: 请把图片放在网站根目录的 assets/img 文件夹下. 例如 assets/img/avatar.png, 并填入 img/avatar.png
  • 外部头像: 头像文件网址.

文章 params.article

协议 license

显示在页面底部

• enabled: 是否在所有文章底部显示协议信息. 可以在文章的 Front Matter 插入 license: false 来单独关闭.
• default: 默认文章协议. 可以在文章的 Front Matter 插入 license: “My custom licence” 来单独关闭.

default: ZHAIJIA.FUN All Rights Reserved.

评论系统 params.comments

是否启用评论 enabled

enabled: false

服务提供商 provider

• disqus
• disqusjs
• utterances
• remark42
• vssue
• waline
• twikoo
• cactus
• giscus
• gitalk
• cusdis

小部件 params.widgets

主页 homepage

普通页

颜色模式 params.colorScheme

是否显示切换按钮 toggle

默认模式 default

可选项:

• auto 自动
• light 亮色
• dark 暗色

自定义菜单 menu

• identifier: Id
• name: 名称
• url: URL
• weight: 权重
• params:
• icon: 图标
• newTab: 是否在新 tab 中打开

主题自带的 SVG 图标来自 Tabler Icons, 存放在 assets/icons 目录下.

你可以在网站根目录下新建同名文件夹, 并下载更多的图标.

主题使用了 params.icon 字段来指定菜单项的图标. params.icon: “archives” 会输出 assets/icons/archives.svg 图标.

融合的菜单

左侧边栏此时有5个菜单项:

• 主页: 非可自定义项, 自动添加且无法删除, 并按当前语言 (zh-cn) 本地化.
• 关于: 融合自 content/page/about/
• Archives: 融合自 content/page/archives/
• Search: 融合自 content/page/search/
• Links: 融合自 content/page/links/

后 4 个菜单项都是融合而来的, 且 “关于” 菜单项已按当前语言 (zh-cn) 本地化.

查看目录 content/page/about/ 可以发现其中有两个文件: index.md 和 index.zh-cn.md, 分别对应本地化语言 en (默认语言) 和 zh-cn. 它们都含有 menu Front Matter, 这使得它们出现在左侧边栏的菜单列表中. 此时只需删除该 menu Front Matter 即可移除对应的菜单项.

如果只需要单一语言菜单项, 比如 zh-cn, 则可只保留 index.md 并对其进行本地化.

最好在 index.md 中设置英文的 slug Front Matter, 比如 slug: “about”, 否则将生成类似 http://localhost:1313/关于/ 的 url.

给分类 / 标签添加图片和简介

创建分类子目录: content/categories/分类名.

创建标签子目录: content/tags/标签名.

然后在该子目录下新建文件 _index.md, 内容如下:

1
2
3
4
5

---
title: "分类名"
description: "简介 Blablabla"
image: "nichijou.jpg"
---

description: 这里是简介.

image: 这里是图片, 和 _index.md 放在同一目录下.

有关 Stack 主题的更多配置, 请参考此处.

修改原型

使用以下的 Markdown 代码替换 Hugo 生成的默认原型文件 archetypes/default.md 的内容:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

---
title: "{{ replace .Name "-" " " | title }}"
description: ""
date: {{ .Date }}
slug: ""
draft: true
image: ""
tags: []
categories: []
---


<!--more-->

该 default.md 默认设置了下列的 Front Matter 字段:

title: 标题, 即将文件名中的 “-” 替换为 " " 后的字符串.

description: 副标题.

date: 创建时间.

slug: 自定义 url, 若为 "" (默认值), 则使用文件名作为 url.

draft: 是否为草稿, 默认为是.

image: 特色图片 (头图), 若为 "" (默认值), 则表示无图.

tags: 标签数组, 默认为空数组.

categories: 分类数组, 默认为空数组.

<!--more-->: 其上一行 (默认为空行) 作为手工摘要, 但 Stack 主题目前并不在各种列表中显示它.

Hugo 将为创建的新文章自动添加上述的 Front Matter 字段.

创建一篇文章

创建示例

以下的命令必须在博客网站项目的根目录下执行!

1
2
3
4
5

hugo new post/`date "+%Y/%m"`/my-page-bundle-post/index.md

可得到:

Content "/path_to/blog.zhaijia.fun/content/post/2022/02/my-page-bundle-post/index.md" created

这将在 Hugo 的内容目录 /path_to/blog.zhaijia.fun/content 下创建新的 Page Bundle my-page-bundle-post (入口为 index.md), 它的原型是 post, 最终存放于按年份和月份区分的子目录 2022/02 下.

新的文章 (index.md) 创建完毕后, 只需一个 Markdown 编辑器就可开始写作.

Page Bundle 是一种内容组织的方式, 它分为:

• Leaf Bundle
• Branch Bundle

这里使用第一种, 即 Leaf Bundle, 表现为:

• 一个自定义名称的子目录 (此处为 my-page-bundle-post).
• 一个入口 Markdown 文件 (即 index.md).
• 一个或多个资源文件 (即图片等文件, 这些文件应该被 Markdown 文件引用).

关于 Page Bundle 的更多信息, 请参考此处.

查看该入口文件 (index.md):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

---
title: "My Page Bundle Post"
description: ""
date: 2022-02-24T18:49:02+08:00
slug: ""
draft: true
image: ""
tags: []
categories: []
---


<!--more-->

可以看到 Hugo 为其自动添加并初始化了来自默认原型文件 archetypes/default.md 的 Front Matter 字段.

同步至 Github 远程 Repo

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

#### 查看所有更新的目录/文件 (包括增删改)
git status

例如:

Untracked files:
  (use "git add <file>..." to include in what will be committed)
	content/

#### 添加更新项
git add content/

#### 提交并进行注释
git commit -m "添加了新文章"

#### 同步至 Github
git push

至此,你的博客网站项目的更新已经同步至 Github (通过 git 命令).

构建静态博客

1
2
3
4

#### 清空 public 目录
rm -fr public/*

hugo --gc --minify

该命令构建静态博客, 并存放在默认的发布目录 public 中.