主题选择

在选择博客主题时，我对比了多个流行的 Hugo 主题，并考虑了它们的评论系统支持、列数以及部署的复杂性。以下是我考虑的主题及其特点：

经过对比，我选择了唯一成功本地部署的 Stack 主题。

安装和配置

参考 官方文档

前提条件

• 安装 Hugo
• 安装 Go
• 安装 Git

新建项目

hugo new site <site_name>
cd <site_name>
git init
touch .gitignore

编辑 .gitignore

参考 community/Golang/Hugo.gitignore

# Custom
/.vscode
**/.DS_Store

# Generated files by Hugo
/public/
/resources/_gen/
/assets/jsconfig.json
hugo_stats.json

# Executable may be added to repository
hugo.exe
hugo.darwin
hugo.linux

# Temporary lock file while building
/.hugo_build.lock

安装主题

参考 使用 Hugo 模块安装 Stack

1. 将项目转换为 hugo module，需要预先安装 go。

   hugo mod init github.com/me/my-new-blog
   

2. 编辑 hugo.toml

   # hugo.toml
   [[module.imports]]
   path = "github.com/CaiJimmy/hugo-theme-stack/v3"
   

3. 安装主题

   hugo mod get -u
   hugo mod tidy
   

配置目录

参考 官方文档

将 hugo.toml 移动至 config/_default

i18n 国际化和菜单

默认语言为英文 en。

1. 从 hugo-theme-stack 下载或复制 i18n 下的语言配置文件，转化为 toml 或直接使用 yaml，放在本地项目 i18n 目录下。

2. 新建 config/_default/languages.toml

   # English
   [en]
   languageCode = "en"
   languageName = "English"
   title = "Laniakea Kamasylvia's Blog"
   weight = 1
   
   # 简体中文
   [zh-cn]
   languageCode = "zh-cn"
   languageName = "简体中文"
   title = "咸鱼之家"
   weight = 2
   

3. 编辑 config/_default/hugo.toml

   copyright = "Laniakea Kamasylvia. All rights reserved."
   defaultContentLanguage = "en"
   defaultContentLanguageInSubdir = true
   enableEmoji = true
   hasCJKLanguage = true
   languageCode = "en"
   

4. 新建英文菜单配置 config/_default/menu.en.toml

   # Home
   [[main]]
   identifier = "home"
   name = "Home"
   url = "/en"
   weight = 1
   [main.params]
   icon = "home"
   newTab = false
   
   # Posts
   [[main]]
   identifier = "posts"
   name = "Articles"
   url = "/en/posts"
   weight = 2
   [main.params]
   icon = "messages"
   newTab = false
   

5. 新建中文菜单配置 config/_default/menu.zh-cn.toml

   # 首页
   [[main]]
   identifier = "home"
   name = "首页"
   url = "/zh-cn"
   weight = 1
   [main.params]
   icon = "home"
   newTab = false
   
   # 文章
   [[main]]
   identifier = "posts"
   name = "文章"
   url = "/zh-cn/posts"
   weight = 2
   [main.params]
   icon = "messages"
   newTab = false
   

日期设置

编辑 config/params.en.md

[dateFormat]
published = "02 Jan 2006"
lastUpdated = "02 Jan 2006 15:04 MST"

编辑 config/params.zh-cn.md

[dateFormat]
published = "2006 年 1 月 2 日"
lastUpdated = "2006 年 1 月 2 日 15:04 MST"

生成唯一固定链接

• 为 Hugo 添加 Abbrlink
• Hugo 永久链接

Hexo-Abbrink 是一个为 Hexo 静态博客框架设计的插件，旨在为每篇博文生成一个固定且唯一的链接。通过使用这个插件，可以避免因文章标题变更导致的链接变动问题，从而保持链接的稳定性和持久性。

虽然 Hugo 没有类似的插件，但可以通过内置方法实现相似的效果。

编辑 archetypes/default.md 的 front-matter。

slug = '{{ now.UnixNano | hash.FNV32a }}'

之后通过 hugo new content index.md 新建文章，文件将位于 content 目录下，手动移动到相应目录。

隐藏内容

在 Hugo 中，如果你想发布一篇文章，使其只能通过 URL 访问，而不会出现在网站的导航菜单或列表页面中，你可以在文章的 front matter 中使用 _build 配置选项。具体来说，你可以设置 list 为 never，这样文章就不会被包含在任何页面集合中，因此不会出现在导航菜单或列表页面上。但是，你可以通过直接访问文章的 URL 来查看这篇文章。

以下是如何在文章的 front matter 中设置的例子：

+++
title = "Only Accessible by URL"
date = 2023-12-01
[_build]
  list = 'never'
+++

（文章内容）

随机封面

使用 Lorem Picsum 服务。在 stack 主题下，封面图是通过 front-matter 的 image 参数设置的。

编辑 archetypes/default.md 的 front-matter。

+++
image = 'https://picsum.photos/seed/{{  .Date | hash.FNV32a }}/800/600.webp'
+++

如需每次访问的图片都随机，可设置

+++
image = 'https://picsum.photos/800/600.webp?random={{  .Date | hash.FNV32a }}'
+++

评论设置

Stack 支持的评论服务很多，我选择的是 Waline。

可参考 Waline 官方文档 进行首次配置。

如已有 Waline 服务，可参考 [hugo-theme-stack/config.yaml] 配置 config/params.toml

[comments]
enabled = true
provider = "waline"

[comments.waline]
dark = "auto"
emoji = "https://cdn.jsdelivr.net/gh/walinejs/emojis/weibo"
serverURL = "<serverURL>" # Waline server URL
requiredMeta = ["nick", "mail"]

再分别设置国际化

config/params.en.toml

[comments.waline]
lang = "en"

config/params.zh-cn.toml

[comments.waline]
lang = "zh-CN"

Admonition

stack 主题不包含 admonition 功能，想要自定义实现 admonition 有多种方案。

• Hugo Stack 主題加入 Admonition 提示框樣式
• Admonitions for My Hugo Website

最简单的方案是使用 hugo-notice 模块。

1. 将 hugo-notice 添加为 Hugo 模块，以便之后能够获取上游的更改

   hugo mod get github.com/martignoni/hugo-notice
   

2. 在 config/_default/module.toml 中，添加一个新的模块部分，并定义 hugo-notice 在你当前使用的主题之前作为要导入的模块。

   [[imports]]
   path = "github.com/martignoni/hugo-notice"
   

使用方法见官方 README。