Hugo 配置文章内容标题索引导航

前提条件

在 Hugo 0.60.0 后我们可以方便的实现文章内标题索引了,因为从这个版本开始引入了 Goldmark MarkDown 生成引擎,基于该引擎在此版本引入了 TableOfContents 配置。

因此,你在尝试此文章的后续内容的前提是确保你的 Hugo 版本是 0.60.0 以上,查看版本命令如下:

1
2
$ hugo version
Hugo Static Site Generator v0.70.0-7F47B99E windows/amd64 BuildDate: 2020-05-06T11:17:50Z

如果你的 Hugo 版本过低,建议先升级版本。

配置文件

1
2
3
4
5
[markup]
    [markup.tableOfContents] #文章导航设置
        endLevel = 3      #3级标题以后不建立索引
        ordered = false   #是否采用有序列表
        startLevel = 2    #2级标题开始建立索引

在你的配置文件中加入上面配置,这里需要注意的是你的配置文件可能不是 toml 格式的,有可能是 yaml 格式或者 json 格式。

添加布局

在主题文件夹中找到文章内容所在文件,例如我的是 themes\icarus\layouts\partials\single_article.html 在文章的内容上面加上一行代码 {{ .TableOfContents }} 即可,代码如下:

1
2
3
4
5
6
{{ partial "article_header" . }}
{{ .TableOfContents }}
<div class="article-entry" itemprop="articleBody">
    {{ .Content }}
</div>
{{ partial "article_footer" . }}

这样你就可以在文章页面预览到目录导航,但是没有任何样式。

重构代码

我们可以把这块设置放到一个专门的组件目录 widgets 下,然后修改上面的代码如下:

1
2
3
4
5
6
{{ partial "article_header" . }}
{{ partial "widgets/tab-of-contents" . }}
<div class="article-entry" itemprop="articleBody">
    {{ .Content }}
</div>
{{ partial "article_footer" . }}

widgets 目录下新建一个 tab-of-contents.html 文件,内容如下:

1
2
3
4
<div id="tab-of-content-area">
    <img id="tab-of-content-button" src="/css/images/switch-on.png"/>
    {{ .TableOfContents }}
</div>

我们添加了一个按钮用来动态开关此功能用的,关于动态开关并如何存储在 cookie 中这个这里不做深入讨论。

标题索引样式

接下来我们就可以在主题的 themes\icarus\static\css 目录中创建一个样式文件,最后引入到 head.html 中,在这里添加样式,例如我的样式文件 tab-of-contents.css 内容如下:

 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
37
38
39
40
41
42
43
44
45
46
47
#tab-of-content-area{
    float: right;
    position: relative;
    right: 24px;
    top: -70px;
    display: none;
}

#TableOfContents{
    position: absolute;
    border-radius: 4px;
    right:50px;
    top:8px;
    display: inline-block;
    width: max-content;
    width:-webkit-max-content;
    width:-moz-max-content;
    max-width: 600px;
    padding: 10px 20px 10px 20px;
    background-color: #515151e1;
    border: 1px solid rgba(81, 81, 81, 0.1);
}

#TableOfContents ul{
    font-size: 16px;
    color: #fff;
}

#TableOfContents ul a{
    color: inherit;
}

#TableOfContents ul ul{
    padding-left: 20px;
    font-size: 14px;
    color:#ddd;
}

#TableOfContents li{
    padding: 5px 0;
    white-space: nowrap; 
    overflow: hidden;
    text-overflow:ellipsis;
}
#tab-of-content-button{
    float: right;
}

你可以根据你的博客风格适当修改我的样式,或者参考一下自己实现自己喜欢的样式,至此我们就完成了给文章内容页添加目录导航功能。