记录Hugo博客搭建过程

前言

这是我个人搭建博客的一个记录，主要作用是记录自己的搭建过程留作备份，或许有一定的参考价值，但请根据使用组建的官方连接获取最新消息，以防文章过期。

一、整体架构

使用Markdown编写博客文章。
使用Hugo 将Markdown 文章转换为HTML 网页代码。
使用PaperMod 作为Hugo 的网页主题，提供美观的界面。
使用Disqus 基于Github Discuss 提供评论功能。
利用Github Pages 部署和访问博客(Github提供的 github.io 域名)。
利用Github Actions 达成自动推送Markdown 到仓库，便会更新网站。

二、效果

如前所述，配置好后就可以专注于使用Markdown写文章，当写好文章使用git push 推送到Github仓库后，Github Actions 就会自动更新博客。

而且由于使用Github Pages 访问博客（如我的博客是: suiyuanla.github.io），并没有实际使用服务器与购买域名，可以实现零成本部署博客。

当然，由于github.io 域名并不稳定，实际上可能需要自行购买域名。当然，如果你是学生的话，Github Education 教育优惠也提供免费域名，请自行挖掘。

三、搭建过程

安装Hugo

Hugo：世界上最快的网站构建框架。（官网自述）：

# 我使用arch linux 以及paru aur helper
paru -S hugo  # 安装hugo

本机部署Hugo 的一个原因是，初始化项目以及新建文章和本地编辑预览需要使用。

创建项目

此处应首先选择一个Hugo 主题，查看主题是否需要特殊的创建选项。

我选用的是PaperMod，去年第一次搭建博客的时候它并不是Hugo 官网主题的第一个，但现在已经放到HUgo官网主题的第一个了。（笑，并不是我随大流，但是确实好用）

Hugo的 config文件支持yaml、toml等格式，而且默认使用toml格式。但是PaperMod主题提供的是yaml，因此创建网站时要指定使用yaml格式：

# 参考：https://github.com/adityatelange/hugo-PaperMod/wiki/Installation
# 我的网站使用suiyuan-blog，可自行替换
hugo new site suiyuan-blog --format yaml

# 使用tree查看创建好的目录结构（非必做）
tree suiyuan-blog

suiyuan-blog
├── archetypes  # 存放模板
├── assets
├── content     # 文件下的posts文件夹存放博客内容
├── data
├── hugo.yaml   # Hugo的配置文件
├── i18n
├── layouts     # 默认没有，添加评论功能时需要使用
├── public      # 默认没有，是我自行设置用于存放生成html文件的文件夹，不上传到Github仓库
├── static      # 用于存放静态资源，比如网站图标
└── themes      # 用于存放主题

# hugo.yaml 配置
baseURL: https://suiyuanla.github.io/   # 我的博客网址
languageCode: zh-CN                     # 网站语言
title: Suiyuan's Blog                   # 网站标题
publishDir: "public"                    # 使用hugo server 命令时生成html的位置，在相对路径public下

安装主题

使用PaperMod推荐的方法：

git submodule add --depth=1 https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod
git submodule update --init --recursive # needed when you reclone your repo (submodules may not get cloned automatically)

# 修改hugo.yaml，添加：
theme: PaperMod

配置主题

由于我使用的是PaperMod，因此很多为PaperMod的自定义选项，还有部分Hugo Template配置，具体配置参见：我的配置。

创建和预览文章

创建文章默认使用的是archetypes/default.md 模板，由于默认生成的是toml格式的头，需要修改为：

# archetypes/default.md
# 注意的是draft为true，说明生成的文章默认是草稿，不会生成html，如果需要生成需要在server上指定--buildDrafts选项
# 如果文章正式写好了要发布，则将draft: true 改为flase
---
title: '{{ replace .File.ContentBaseName "-" " " | title }}'
date: "{{ .Date }}"
draft: true
---

注意：如果想在文章中方便的添加图片，并使用相对路径来访问图片，需要将一篇文章放在一个文件夹内（如：content/posts/blog-1/），然后文章以index.md命名。假如有张图片路径为：blog-1/imgs/1.jpg，就可以在index.md内通过![text](imgs/1.jpg)来显示这张图片。详细内容参考：Hugo: Page resources

可以使用下面命令创建和预览文章：

# 会在content/posts/ 创建test.md，可以用vscode打开suiyuan-blog这个文件夹作为项目，编写Markdown
hugo new content content/posts/test.md
hugo server --buildDrafts   # --buildDrafts 会build我们新建的草稿，在浏览器访问localhost:1313可以看到搭建的网站

开启Latex渲染

注意：此部分内容由于使用PaperMod主题，因此配置与官网设置不同，如果主题不同请参考下面给出的参考链接。

由于阅读论文等一些内容时，会使用Latex书写数学公式，因此需要开启Markdown的Latex渲染。此部分参考: Hugo: Mathematics in Markdown、Hugo-PaperMod: How to enable Math Typesetting in PaperMod?。首先在hugo.yaml，添加下列内容:

markup:
  goldmark:
    extensions:
      passthrough: # 此项是将指定的分隔符以及分隔符内容直通给HTML,以便Katex等能够渲染
        delimiters:
          block: # 块级符号
            - - \[
              - \]
            - - $$
              - $$
          inline: # 行内符号
            - - \(
              - \)
        enable: true
params:
  math: true # 此项的作用是为`md`文件默认开启Latex渲染

然后创建文件：layouts/partials/extend_head.html，在里面添加下列内容：

{{ if or .Params.math .Site.Params.math }}
<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css"
  integrity="sha384-n8MVd4RsNIU0tAv4ct0nTaAbDJwPJzDEaqSD1odI+WdtXRGWt2kTvGFasHpSy3SV"
  crossorigin="anonymous"
/>
<script
  defer
  src="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.js"
  integrity="sha384-XjKyOOlGwcjNTAIQHIpgOno0Hl1YQqzUOEleOLALmuqehneUG+vnGctmUb0ZY0l8"
  crossorigin="anonymous"
></script>
<script
  defer
  src="https://cdn.jsdelivr.net/npm/[email protected]/dist/contrib/auto-render.min.js"
  integrity="sha384-+VBxd3r6XgURycqtZ117nYw44OOcIax56Z4dCRWbxyPt0Koah1uHoK0o4+/RRE05"
  crossorigin="anonymous"
></script>
<script>
  document.addEventListener("DOMContentLoaded", function () {
    renderMathInElement(document.body, {
      delimiters: [
        { left: "\\[", right: "\\]", display: true }, // block
        { left: "$$", right: "$$", display: true }, // block
        { left: "\\(", right: "\\)", display: false }, // inline
      ],
      throwOnError: false,
    });
  });
</script>
{{ end }}

评论功能

这部分由于是一年前部署的，已经没有什么印象了（开摆），请参考PaperMod Features Comments，以及Hugo Comments。

部署过程

此部分参考Github Pages、Github Actions。

如果想通过username.github.io直接访问博客，需要建立一个名称为username.github.io的仓库。
然后在Actions 里搜索名称为hugo 的Github Action 并部署，全默认配置不需要修改。
在仓库的settings->Pages 开启Pages功能，Build and deployment -> Source 选择Github Actions
将创建的网站项目推送到创建的仓库，待Action执行完成就可以访问username.github.io 看到自己搭建的博客。

前言#

一、 整体架构#

二、效果#

三、搭建过程#

安装Hugo#

创建项目#

安装主题#

配置主题#

创建和预览文章#

开启Latex渲染#

评论功能#

部署过程#

前言