使用 Hugo + DoIt 构建个人博客

Noah 收录于类别 DevOps

2024-03-14 2024-08-29 约 3399 字预计阅读 7 分钟

0. 为何使用 Hugo

个人笔记或是博客通常是不只包含文本，还有不同字体大小、程序代码、表格、流程图、LaTex、图片等。使用 Word 或有道云笔记等程序编写个人笔记，不易分享、不易在各平台中相互转换，还需要关注段落格式等问题，较为繁琐，因此 Markdown 格式在个人笔记或技术文档方面较为通用。

Hugo 可以直接将 Markdown 内容渲染为纯静态的 HTML，然后通过 NGINX 等搭建 Web 服务，其有以下好处：

资源占用小：纯静态页面意味着无后端业务代码、无数据库，基本不消耗系统资源。
安全性高：纯静态页面，相较于 LAMP + WordPress 之类个人博客，使用组件少，且不存在后端交互。
易于同步：本地创建 Git 仓库，通过网络同步到 GitHub 等代码托管平台，不需要受限与笔记导出或是网盘等付费服务。
配置简单：可以直接将托管到 GitHub Pages 或 CloudFlare Pages，甚至不需要购买服务器、购买域名、配置证书等操作。

本站也是基于 Hugo，使用 DoIt 主题，托管至 CloudFlare Pages。关于 CloudFlare，用过 VLESS + WebSocket + CloudFlare CDN 等方式搭建代理服务的人应该不会陌生。另外 Pigsty 社区冯老师写的《吊打公有云的赛博佛祖 Cloudflare》（注：外链至微信公众平台）这篇文章中简单介绍了 CloudFlare ，值得阅读。

1. 安装 Hugo

参考 Hugo官方文档。

bash

# 方法1：Debain系可以直接通过apt安装
# 这种方法安装的Hugo版本可能相对落后，不推荐。
sudo apt install hugo

--------------------------------------------------------------------------------------------------

# 方法2：Debain系通过下载.deb包安装，在官方GitHub仓库的Release下载二进制安装包（注意，要安装hugo_extended版本）
# https://github.com/gohugoio/hugo/releases
wget https://github.com/gohugoio/hugo/releases/download/v0.119.0/hugo_extended_0.119.0_linux-amd64.deb 

# 安装.deb包
dpkg -i hugo_extended_0.119.0_linux-amd64.deb

--------------------------------------------------------------------------------------------------

# 方法3：Windows或其他Linux发行版：下载对应的二进制程序，为其添加环境变量
# https://github.com/gohugoio/hugo/releases
wget https://github.com/gohugoio/hugo/releases/download/v0.119.0/hugo_extended_0.119.0_linux-amd64.tar.gz

# 解压
tar -zxvf hugo_extended_0.119.0_linux-amd64.tar.gz -C /usr/local/hugo

# 添加环境变量
sudo echo 'export PATH="$PATH:/usr/local/hugo"' >> /etc/profile
source /etc/profile

2. 创建网站并安装主题

参考 DoIt官方文档。

bash

# 使用Hugo创建站点
hugo new site blog

# 进入站点目录
cd blog

# 初始化Git仓库
git init

# 安装DoIt主题作为当前Git仓库的子模块
git submodule add https://github.com/HEIGE-PCloud/DoIt.git themes/DoIt

3. 配置网站

参考上述 DoIt 官方文档的基础配置，修改站点根目录下的 hugo.toml 文件，后续可根据需求自行修改。

toml

baseURL = "http://example.org/"
# [en, zh-cn, fr, ...] 设置默认的语言
defaultContentLanguage = "zh-cn"
# 网站语言, 仅在这里 CN 大写
languageCode = "zh-CN"
# 是否包括中日韩文字
hasCJKLanguage = true
# 网站标题
title = "我的全新 Hugo 网站"

# 更改使用 Hugo 构建网站时使用的默认主题
theme = "DoIt"

[params]
  # DoIt 主题版本
  version = "0.2.X"

[menu]
  [[menu.main]]
    identifier = "posts"
    # 你可以在名称 (允许 HTML 格式) 之前添加其他信息, 例如图标
    pre = ""
    # 你可以在名称 (允许 HTML 格式) 之后添加其他信息, 例如图标
    post = ""
    name = "文章"
    url = "/posts/"
    # 当你将鼠标悬停在此菜单链接上时, 将显示的标题
    title = ""
    weight = 1
  [[menu.main]]
    identifier = "tags"
    pre = ""
    post = ""
    name = "标签"
    url = "/tags/"
    title = ""
    weight = 2
  [[menu.main]]
    identifier = "categories"
    pre = ""
    post = ""
    name = "分类"
    url = "/categories/"
    title = ""
    weight = 3

# Hugo 解析文档的配置
[markup]
  # 语法高亮设置 (https://gohugo.io/content-management/syntax-highlighting)
  [markup.highlight]
    # false 是必要的设置 (https://github.com/dillonzq/LoveIt/issues/158)
    noClasses = false

4. 创建文章

建议每个文章使用单独的目录，这样每个文章中使用的图片资源也放置在单独的目录下，易于区分。

bash

# 创建一篇新的博客
hugo new posts/xray/index.md

修改 index.md 的 Markdown Headers，添加信息。

txt

---
title: "文章名称"

date: 2023-10-13T16:25:03+08:00

# 草稿模式，为true则使用hugo生成网站时不会包含该文章。
# draft: true

# 启动Mermaid流程图
mermaid: true

# 标签
tags:
  - 文章标签

# 分类
categories:
  - 文章分类
---

编写文章，注意Markdown Headers中 draft 的配置，该值默认为 true，即开启草稿模式。

5. 预览网站

使用 hugo server -D 命令，实时预览网站效果，该选项会显示草稿模式(draft: true)的文章。
使用 hugo server 命令预览网站效果，该选项不会显示草稿模式(draft: true)的文章。
使用 hugo 命令生成静态网站，生成的网站的根目录为hugo项目目录下的public目录。

此时的项目目录如下：

bash

├── README.md                           [当前文件，即项目说明文件]
├── archetypes                          [Markdown Headers模板文件目录]
│   └── default.md                          [Markdown Headers模板，创建新的文章时，会自动添加至Markdown前面]
├── hugo.toml                           [项目的主配置文件]
├── content                             [内容目录，网站自定义的资源存放于此]
│   ├── assets                              [静态资源文件，主要是作者头像和网站ICO]
│   │   ├── avater.png
│   │   └── favicon.ico
│   └── posts                               [具体文章目录，其下的每个目录即一篇文章]
│       └── xray                                [其中一篇文章目录，所有文章]
│           ├── assets                          [这篇文章中用到的静态图片资源]
│           │   └── image-20231009112514737.png
│           └── index.md                        [文章的Markdown格式,Markdown Headers中写明文章标题、标签等]
├── data                                [存储Hugo生成网站时应用的配置文件，当前为空]
├── i18n                                [多语言配置，当前为空]
├── layouts                             [网站模板目录，默认为空]
├── public                              [使用hugo命令生成的静态网站的目录]
├── resources                           [资源目录]
├── static                              [存放网站静态内容，使用Hugo生成静态网站时会自动将该目录复制到网站根目录 下]
└── themes                              [存放Hugo主题的目录]
    └── DoIt
        └── theme.toml

6. 部署网站

可部署到 GitHub Pages、Cloudflare Pages 等，也可自行部署到 Web 服务器上，此处以 NGINX 环境为例。修改NGINX配置文件/usr/local/nginx/conf/nginx.conf:

nginx

server {
        # 监听80端口
        listen 80;
        # 设置主机名称
        server_name localhost;

        location / {
                        # 网站目录
                root /usr/local/DoIt_Blog/public;
                index index.html index2.html index3.html;
        }
        error_page 404 /404.html;

}

考虑到NGINX可能配置多个服务，不建议使用上述方法直接修改主配置文件。修改NGINX主配置文件的http块，添加如下配置：

nginx

include /usr/local/nginx/conf/conf.d/*.conf;

在对应路径下创建.conf配置文件，建议以端口名或服务方式命名。

上述只是测试环境的 NGINX 的部署，实际生产环境应该自行修改网站目录、严格配置网站文件权限、配置 SSL 证书、启用 CDN 等。

7. 兼容性问题(BUG)

使用 Typora 等 Markdown 编辑器编写的文档可能和 Hugo+DoIt 主题渲染出的网页可能存在 BUG，以 Mermaid 流程图为例：

markdown

1.Typora、GitHub支持的Mermaid流程图代码(正常代码格式)

```mermaid
graph LR;
        A(客户端XRAY) --> |国内流量:直连|B[国内目标服务器]
    A --> |国外流量:XRAY协议|C(服务端XRAY)
    subgraph 服务端路由规则
        C --> |国内流量| D[阻断所有回国流量]
        C --> |匹配域名| E[WARP解锁ChatGPT,Netflix]
        C --> |默认规则| F[国外目标服务器:Google,Youtube]
    end
```

graph LR;
        A(客户端XRAY) --> |国内流量:直连|B[国内目标服务器]
    A --> |国外流量:XRAY协议|C(服务端XRAY)
    subgraph 服务端路由规则
        C --> |国内流量| D[阻断所有回国流量]
        C --> |匹配域名| E[WARP解锁ChatGPT,Netflix]
        C --> |默认规则| F[国外目标服务器:Google,Youtube]
    end

在Hugo + DoIt中，使用 hugo server -D 或者 hugo server 命令预览网页，很可能无法正确显示Mermaid图，但使用 hugo 命令生成静态网站后，部署在Web Server（如NGINX）上，Mermaid图可以正常显示。

另一个BUG：GitHub在渲染Mermaid图时，若中括号内的节点名称中含有部分特殊字符（如中文括号、中文顿号等），会导致无法渲染成功，例如 E[WARP解锁ChatGPT,Netflix] 可被正常渲染，但 E[WARP解锁ChatGPT、Netflix] 中的中文顿号会导致GitHub渲染报错 Unable to render rich display Diagram error not found. 。

8. 推送至 GitHub

bash

# 进入项目根目录
cd /usr/local/DoIt_Blog

# 设置远端GitHub仓库
git remote add origin git@github.com:your_name/your_repositories.git

# 本地文件提交至本地仓库缓冲区
git add .

# 本地文件提交至本地仓库归档去并添加说明
git commit -m "更新说明"

# 推送到远端仓库主分支
git push -u origin master

9. 将博客部署在 CloudFlare Pages

打开 CloudFlare控制面板，选择左侧菜单 Workers and Pages – 创建 – Pages – 连接到Git – 添加账户并选择存储库 – 选中存储库 – 开始设置 ，进入 “设置构建和部署” 页面。

在 “设置构建和部署” 页面，填写项目名称，若项目不与其他用户构造的项目名重复，则构造的项目URL即为「项目名称.pages.dev」。

在 框架预设 选项中选择 Hugo 后，构建命令和输出目录会自动生成，无需手动调整。

展开 环境变量（高级） ，点击 添加环境变量，以此指定使用的 Hugo 版本。变量名称填写 HUGO_VERSION ，值填写为具体的 Hugo 版本，如 0.127.0 ，然后点击 保存并部署 ，3-5分钟内即可完成部署。

若需要自定义域名，可以购买域名并通过修改 NS 记录交由 CloudFlare 解析，在 Workers 和 Pages 中找到自定义域，输入自定义域名并点击激活域后，CloudFlare 会自动添加 CNAME 记录，待 DNS 信息同步完成后即可使用自定义域名访问。

DoIt 建议使用最新版本的 Hugo，若使用旧版本可能导致部署失败，版本可以参考 Hugo Releases 。