一、安装

1
2
3
4
5
6
7

# 首先初始化一个站点项目
hugo new site hugo-book
cd hugo-book
# 下载主题
git clone <https://github.com/alex-shpak/hugo-book.git> themes/book
# 指定主题为“book”启动便可以看到效果了
hugo server -t book

二、使用

首先将主题中的文章模板复制到本项目的模板目录下：

1
2
3

cp -R themes/book/archetypes .
# 删除原来的default.md
rm archetypes/default.md

下面我们就可以使用新复制过来的模板来创建文章了：

1
2
3

hugo new docs/章节一.md
hugo new docs/章节二.md
hugo new docs/章节三.md

此时如果启动的话，页面仍是空白的，看不到任何一个章节，因为这几个章节的文档内容是空的。

我们编辑“章节一.md”：

1
2
3
4
5
6
7

这是章节一。

# 一级标题

## 二级标题

### 三级标题

此时，启动服务，页面便可以看到章节一了：

https://img.hongmao.run/blog/2021/07/hugo-book-init.png

但是我们可以看到有个问题是：一级标题无法在目录中展示。

我们往“章节二.md”和“章节三.md”中随意添加点内容，使其可以在首页展示。但是展示后的效果确是这样的：

https://img.hongmao.run/blog/2021/07/hugo-book-menu-1.png

章节三跑到了章节二的前面。这就是由于使用了默认的菜单排列方式，且没有为其指定权重（文章md文件头部的weight属性，数字越大顺序越往后）导致的。

我们为每篇文章指定权重，以用来排序：

1
2
3
4
5

---
title: "Spring框架文档"
# 就是该字段，数字越大，该文章将越往下
weight: 1
---

也可以通过绑定菜单的方式来实现，创建文件“content/menu/index.md”，按照如下方式排列：

1
2
3
4
5
6

+++
headless = true
+++
- [章节一]({{< relref "/docs/章节一" >}})
- [章节二]({{< relref "/docs/章节二" >}})
- [章节三]({{< relref "/docs/章节三" >}})

然后，再修改配置文件，添加如下配置：

1
2
3

[params]
  # 设置菜单栏排列的方式为绑定，且指定菜单的文件
  BookMenuBundle = '/menu'

启动服务后便可发现，目前菜单的排列是按照我们设定的方式排列的了。但是，这种绑定菜单的方式在本主题内已被标记废弃，会在启动时打印如下内容：

1

WARN 2021/07/28 20:14:35 Bundle menu mode is deprecated and will be removed

所以，还是建议使用“文件树”模式生成菜单。

三、部分特性的使用

1. 折叠菜单

只要在想要折叠的菜单目录对应的“_index.md”头描述中开启对应开关即可：

1
2

# 但是，仅针对使用“文件树”模式的菜单时，该设置才生效
bookCollapseSection: true

2. 使用提示框

代码如下：

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

{{< hint info >}}
**Markdown content**  
Lorem markdownum insigne. Olympo signis Delphis! Retexi Nereius nova develat
stringit, frustra Saturnius uteroque inter! Oculis non ritibus Telethusa
{{< /hint >}}

{{< hint warning >}}
**Markdown content**  
Lorem markdownum insigne. Olympo signis Delphis! Retexi Nereius nova develat
stringit, frustra Saturnius uteroque inter! Oculis non ritibus Telethusa
{{< /hint >}}

{{< hint danger >}}
**Markdown content**  
Lorem markdownum insigne. Olympo signis Delphis! Retexi Nereius nova develat
stringit, frustra Saturnius uteroque inter! Oculis non ritibus Telethusa
{{< /hint >}}

目前仅支持上述三种提示框，效果如下：

https://img.hongmao.run/blog/2021/07/hugo-book-hints.png

嘿嘿，但是我们可以通过自定义样式来扩展提示框，比如修改它的样式、增加新的提示框等等。

首先新建一个文件：“assets/_custom.scss”，然后在其中便可以修改、增加相关的类来达到我们想要的效果：

 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

// 新增hint类型：tip
.markdown .book-hint.tip {
    border-color: #3375b4;
    background-color: #e9f1f6
}

// 新增hint类型：note
.markdown .book-hint.note {
    border-color: #4a692d;
    background-color: #ecf1e8;
}

// 修改原hint类型样式：warning
.markdown .book-hint.warning {
    border-color: #cc882f;
    background-color: #fff9e4;
}

// 新增hint类型：important
.markdown .book-hint.important {
    border-color: #af2418;
    background-color: #f9ebeb;
}

// 新增hint类型：caution
.markdown .book-hint.caution {
    border-color: #b0401c;
    background-color: #f9ebeb;
}

然后效果如下：

https://img.hongmao.run/blog/2021/07/hugo-book-hints-custom.png

3. 使用tab页

代码如下：

1
2
3
4
5

{{< tabs "uniqueid" >}}
{{< tab "MacOS" >}} # MacOS Content {{< /tab >}}
{{< tab "Linux" >}} # Linux Content {{< /tab >}}
{{< tab "Windows" >}} # Windows Content {{< /tab >}}
{{< /tabs >}}

效果如下：

https://img.hongmao.run/blog/2021/07/hugo-book-tab.png

指定logo后，logo会显示在搜索框的上方。该logo的地址既可以是网络地址，也可以是相对地址。

1
2
3

[params]
  # 设置Logo，可以使用网络上的地址，也可以将logo放在static包下，然后在此指定相对路径，例如：logo.png
  BookLogo = '<https://xxx.xxx.png>'

5. 指定网站favicon

将图标命名为“favicon.png”，注意后缀也不可以错，让后将该文件放入站点的“static”目录下即可。

四、美化

1. 自定义代码字体

前面我们也提到过了，本主题支持自定义部分样式，可以在“assets/_custom.scss”文件中添加如下样式：

1
2
3
4

/* 定制化代码样式，包括行内代码和代码块 */
code {
    font-family: Monaco,Consolas,Menlo,dejavu sans mono,bitstream vera sans mono,courier new,monospace
}

2. 自定义代码高亮样式

本设定与当前主题无关了，它属于hugo本身的功能，方法是在配置文件中添加如下配置：

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

[markup]
  [markup.highlight]
    anchorLineNos = false
    codeFences = true
    guessSyntax = false
    hl_Lines = ""
    lineAnchors = ""
    lineNoStart = 1
    lineNos = false
    lineNumbersInTable = true
    noClasses = true
    style = "dracula"
    tabWidth = 4

style样式可以在https://xyproto.github.io/splash/docs/all.html去找，只不过在本主题下有个问题，部分样式的背景颜色为白色，而本主题也是白色，可能会展示很奇怪，如下所示：

https://img.hongmao.run/blog/2021/07/hugo-book-code-xcode.png

可以看到，根本看不出代码的边界在哪，只有在选中该代码块时才会出现边框。我试过覆盖这块的样式，也不能解决，最终找了个黑色背景的样式：dracula。

问题

1. 文章内部的目录中无法展示一级标题

可以通过hugo的配置来解决：

1
2
3
4
5
6
7
8

[markup]
  [markup.tableOfContents]
    # 纳入目录的最小标题级别，默认为3
    endLevel = 3
    # 是否排序，其实就是是否在目录的前面添加序号“1. ”、"2. "等等
    ordered = false
    # 纳入目录的最大标题级别，默认为2
    startLevel = 2

其实，我觉得文章内的目录中不展示一级标题倒不是个问题，因为一级标题最好是用于设定本篇文章的标题。