博客迁移-1：调研hugo框架zzo主题

1. 简介

本博客站使用hugo引擎，使用zzo主题并略作调整搭建起来。本文记录hugo的概念说明以及使用备忘。

2. 说明

2.1 目录结构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
hex-go.github.io
├── archetypes/      # 博客模板目录
│   └── default.md
├── config/          # 配置文件
├── content/         # 博客主要内容，也是网站资源的顶层
├── public/          # 默认存放hugo构建后的编译文件(gitignore)
├── resources/       # 缓存一些文件以加快生成速度(gitignore)
├── static/          # 静态文件
├── themes/          # 主题（git add submodule）
├── .gitignore       # 不进行版本控制的文件和目录
├── .gitmodules      # 记录主题submodule信息
├── Makefile         # make 命令
└── README.md        # 本文档

2.2 内容管理

hugo的顶层为./content/<DIRECTORIES>，是用于确定布局等的内容类型。要了解有关部分的更多信息，包括如何嵌套它们，请参阅部分。

Page bundles: Hugo 通过Page bundles来表示页面相关的图像和其他资源。

_index.md 在 Hugo 中具有特殊作用。它允许你在列表模板中添加前置内容和内容。这些模板包括章节模板、分类模板、分类术语模板和主页模板。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
.
└── content
    └── about
    |   └── index.md       // <- https://example.org/about/
    ├── posts
    |   ├── firstpost.md   // <- https://example.org/posts/firstpost/
    |   ├── happy
    |   |   └── ness.md    // <- https://example.org/posts/happy/ness/
    |   └── secondpost.md  // <- https://example.org/posts/secondpost/
    └── quote
        ├── first.md       // <- https://example.org/quote/first/
        └── second.md      // <- https://example.org/quote/second/

2.1 配置

配置文件

1
2
3
4
5
./config/
└── _default
    ├── config.toml
    ├── menus.toml
    └── params.toml

2.1.1 内容宽度

如果想增大博客屏幕尺寸，只需更改params.toml文件中的viewportSizeref-1值即可。一共5个选项，对应尺寸为：

选项	对应宽度
naroow	800px
normal	960px（默认）
wide	1280px
wider	1440px
widest	1600px

2.1.2 目录设置(Toc)

config.toml中关于博客目录Toc的设置 – 设置博客目录以Hx起始，以及截止Hx：

1
2
3
4
[markup.tableOfContents]
    endLevel = 4
    ordered = false
    startLevel = 2

必须设置此配置参数，否则 toc 将无法运行。以上面配置为例，startLevel和endLevel意味着最多使用 h2 标签，最少使用 h4 标签作为文章标题。而 h1、h5、h6 标签不会包含在 TOC 元素中。

博客目录可以在params.toml（全局生效）中设置，也可以在单一博客的Front-Matters(当前博客)中设置。

params.toml配置举例:

1
2
3
4
5
6
7
# 博客目录
enableToc = true       # 目录是否启用
hideToc = false        # 目录是否隐藏
enableTocSwitch = true # 是否启用 目录隐藏\显示 按钮
tocFolding = false     # 目录是否动态显示
tocPosition = "outer"  # 文档目录结构位置: 内联(inner)、外嵌(outer)。
tocLevels = ["h2", "h3", "h4"] # 目录所包含的标题，还受config.toml中的markup.tableOfContents配置影响

参数	说明
enableToc	在所有文章中是否显示目录，true: 显示；false: 不显示
toc	在所有文章中完全取消提示。这是 enableToc 的别名
enableTocSwitch	开启目录隐藏\显示按钮，true: 开启；false: 隐藏
hideToc	隐藏toc(搭配enableTocSwitch=true时,默认隐藏目录)。true: 隐藏; false: 不隐藏
enableTocContent	在主文章中显示提示，不在侧边栏中显示。
tocPosition	oneof [inner outer]。 inner: toc将位于边框内;；outer: Toc将位于边框之外。
tocFolding	是否动态显示目录, 默认折叠,查看至相应内容时展开当前目录
tocLevels	标题是否在目录中显示，优先级没有`config.toml`中的高 minimum h2, maximum h4 in your article

2.1.3 侧边栏设置

参数	说明
enableBio	Bio(biography),生平
enableBioImage
enableSidebar	侧边栏显示
enableSidebarTags
enableSidebarSeries	侧边栏 - 系列显示
enableSidebarCategories	侧边栏 - 分类显示
enableHomeSidebarTitles	启用主页侧边栏字幕
enableListSidebarTitles
itemsPerCategory
enableSidebarPostsByOrder
sidebarPosition

2.2 博客结构

如何修改
zzo主题关于sidebar的标签、分类、系列的排序，未设置配置项，需要找到关于sidebar的内容部分进行调整。
sidebar关于这些的内容在在themes/zzo/layouts/partials/sidebar目录下，分别为sidebar-home.html与sidebar-list.html
如何生效
由于使用git 子模块引用的主题文件，需要执行以下操作，引用最新提交的zzo主题文件
- 首先,进入包含子模块的父仓库的根目录。
- 使用以下命令来更新子模块内容：
  添加 --init 选项, 可在更新子模块的同时，初始化子模块
  1
  git submodule update --remote --init
- 在父仓库中提交子模块变更
  1 2
  git add path/to/submodule # 将子模块的路径添加到父仓库的暂存区 git commit -m "Update submodule to latest commit"

2.3 博客编写

2.3.1 Archetype(模板)

Hugo提供Archetypes(原型)能力，定义通用的模板, 一是为了保证博客内容和数据的一致性; 二是为了快速生成,提高效率。

如何创建

archetype需要以类型为名称,并将模板文件保存至archetypes/目录下,以golang模板举例:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
---
title: '{{ replace (replaceRE `\d{4}-\d{2}-\d{2}-` "" .Name) "_" ": " |title}}'
categories:
  - Golang
tags:
  - Go
subtitle: ""
description:
date: {{ .Date }}
toc: true

---
## 1.简介


## 2.说明


## 3.总结


## 4.参考

方法
replaceRE: 根据正则替换,将符合正则表达式的内容替换为指定字符, 上面模板将.Name中的日期前缀置为空;
replace: 将字符串中的某些字符替换为特定字符, 此处将去除日期前缀的.Name中的_字符替换为:
变量Page variables
.Name: 当前页面名称
.Date: 返回给定页面的日期

如何使用
根据指定类型,创建博客
kind: 博客类型, 需要与archetypes目录下的模板名称保持一致, 此处以golang举例;
target_file_path: 博客生成位置, 此处以content/posts/golang/2020-05-25-Go-Modules版本控制和依赖管理.md举例;
1
hugo new --kind <kind|golang> <target_file_path|content/posts/golang/2020-05-25-Go-Modules版本控制和依赖管理.md>

2.3.2 Front-Matters

Hugo将每个博客的开头区块定义为Front Matter(扉页)，定义一些当前博客相关的内容、设置。

2.3.3 引用

在 Hugo 中，通过ref 和 relref创建链接引用或获取其他页面的元数据。根据hugo文档与源码注释，ref 用于获取相对于 Hugo 根目录的页面路径，
relref 用于获取相对于当前页面的页面路径。但经过翻阅源码、测试，两者没有区别，建议选用ref即可

Heading IDs

hugo会自动给文档标题增加Head_ID, 可以通过此引用具体的小节。但部分字符会被转义，因此点击目标标题的索引查看，便于确认转义后的Head_ID

举例说明：

文章路径中的.md后缀可带、可不带；

示例目录结构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
.
└── content
    ├── page
    |   ├── about.md                                       // <- https://example.org/posts/about/
    |   ├── friend.md                                      // <- https://example.org/posts/friend/
    |   └── share.md                                       // <- https://example.org/posts/share/
    └── posts
        ├── kubernetes
        |   └── 2019-12-13-k8s小技巧.md                     // <- https://example.org/posts/kubernetes/2019-12-13-k8s小技巧/
        └── 个人工具
            ├── 2019-06-22-hexo--常用命令备忘录.md           // <- https://example.org/posts/个人工具/2019-06-22-hexo--常用命令备忘录/
            └── 2022-09-30-博客迁移-1_调研hugo框架zzo主题.md  // <- https://example.org/posts/个人工具/2022-09-30-博客迁移-1_调研hugo框架zzo主题/

base 页面为 content/posts/个人工具/2022-09-30-博客迁移-1_调研hugo框架zzo主题.md

1
2
[friend](https://hex-go.github.io/page/friend/)
[about](https://hex-go.github.io/page/about/)

相对引用文章
相对引用示例-引用文章
相对引用文章，标题
相对引用示例-异文章引用标题
当前文章，引用标题
相对引用示例-当前文章引用标题
绝对引用标题
绝对引用-标题示例

2.3.3 相关内容

此配置影响博客结尾的相关文章，由于相关文章设置最大显示5条(zzo主题中已写死)
自定义相关内容算法中不同因素的权重，结合threshold=80，相关文章最大5条

相同系列的文章，也必定为相关文章（合理）
文章>3个相同关键字，则为相关文章（合理）
文章>3个相同tag，则为相同文章(合理)
日期不纳入相关性计算（合理）

 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
27
28
29
30
31
32
33
34
35
36
[related]                                # 相关内容设置
  includeNewer = false                   #   包括更新日期比当前文章新的相关文章
  threshold = 80                         #   定义两篇文章之间标签匹配的阈值。标签匹配度高于阈值的文章将被视为相关文章。
  toLower = false                        #   将标签、关键字转换成小写进行匹配，即 false：区分大小写
[[related.indices]]                      #   相关性 - 系列
    name = 'series'                      #     名称，series(系列)
    weight = 90                          #     权重，在相关性计算中的权重，范围为正整数，值越大相关性越强，0：不进行相关性计算
    type = 'basic'                       #     相关性类型， basic基本类型      
    applyFilter = false                  #     是否应用过滤器，false：不应用     
    cardinalityThreshold = 0             #     关键字的基础阈值，0：没有基础阈值     
    pattern = ''                         #     正则表达式模式，可用正则进行过滤      
    toLower = false                      #     转小写                   
[[related.indices]]                      #   相关性 - 关键字
    name = 'keywords'                    #     名称，keywords(关键字)
    weight = 30                          #     权重，30：标签在相关性计算中 权重较低
    type = 'basic'
    applyFilter = false
    cardinalityThreshold = 0
    pattern = ''
    toLower = false
[[related.indices]]                      #   相关性 - 标签
    name = 'tags'                        #     名称，tag(标签)
    weight = 30                          #     权重，30：标签在相关性计算中 权重较低
    type = 'basic'
    applyFilter = false
    cardinalityThreshold = 0
    pattern = ''
    toLower = false
[[related.indices]]                      #   相关性 - 日期
    name = 'date'                        #     名称，date(日期)
    weight = 0                           #     权重，0：日期不进行相关性计算
    type = 'basic'
    applyFilter = false
    cardinalityThreshold = 0
    pattern = ''
    toLower = false

2.3.4 代码块

代码块增加文件路径作为标题
1
echo hello!
将行号替换为指定字符, 比如 >或$, 以>举例：
1
echo hello!
多语言代码块
1
System.out.println('Hello World!');
1
console.log('Hello World!');

3.总结

4.参考

Viewport Size – Z Themes Documentation (zzo-docs.vercel.app)

目录