使用Hugo框架搭建博客的过程 - 页面模板
前言
最初在制作友链界面时，没有学习Hugo框架，一头雾水。网上有关的教程甚少，只能去学一遍Hugo。
在学习Hugo的过程中，了解了列表模板，分类模板。开发了几个功能页面，如：留言板，友链，记忆分类等。
本文介绍这些功能页面。
里程碑页面
首先需要了解头部参数type，通过type指定文章使用的模板类型，默认为page类型。
要注意特殊模板的文章放在一般content根目录下，模板放在layouts目录下。
里程碑界面依据themes\LoveIt\layouts\posts\single.html修改，删除赞赏，相关文章推荐等功能。
{{- define "title" }}{{ .Title }} - {{ .Site.Title }}{{ end -}}
{{- define "content" -}}
{{- .Scratch.Delete "this" -}}
{{- $params := .Scratch.Get "params" -}}
{{- $toc := $params.toc -}}
{{- if eq $toc true -}}
{{- $toc = .Site.Params.page.toc | default dict -}}
{{- else if eq $toc false -}}
{{- $toc = dict "enable" false -}}
{{- end -}}
{{- /* Auto TOC */ -}}
{{- if ne $toc.enable false -}}
<div class="toc" id="toc-auto">
<h2 class="toc-title">{{ T "contents" }}</h2>
<div class="toc-content{{ if eq $toc.auto false }} always-active{{ end }}" id="toc-content-auto"></div>
</div>
{{- end -}}
<article class="page single special">
{{- /* Title */ -}}
<h1 class="single-title animated flipInX">
<i class="fas fa-monument fa-fw"></i> {{ .Title }}
</h1>
{{- /* Static TOC */ -}}
{{- if ne $toc.enable false -}}
<div class="details toc" id="toc-static" kept="{{ if $toc.keepStatic }}true{{ end }}">
<div class="details-summary toc-title">
<span>{{ T "contents" }}</span>
<span><i class="details-icon fas fa-angle-right"></i></span>
</div>
<div class="details-content toc-content" id="toc-content-static">
{{- dict "Content" .TableOfContents "Ruby" $params.ruby "Fraction" $params.fraction "Fontawesome" $params.fontawesome | partial "function/content.html" | safeHTML -}}
</div>
</div>
{{- end -}}
{{- /* Content */ -}}
<div class="content" id="content">
{{- dict "Content" .Content "Ruby" $params.ruby "Fraction" $params.fraction "Fontawesome" $params.fontawesome | partial "function/content.html" | safeHTML -}}
</div>
<div id="post-footer"></div>
{{- /* Comment */ -}}
{{- partial "comment.html" . -}}
</article>
{{- end -}}
这个模板也可以制作“爱情故事”。
关于页面
相对里程碑界面，关于界面又删除了目录。
{{- define "title" }}{{ .Title }} - {{ .Site.Title }}{{ end -}}
{{- define "content" -}}
{{- $params := .Scratch.Get "params" -}}
<article class="page single special">
{{- /* Title */ -}}
<h1 class="single-title animated flipInX">{{ .Title }}</h1>
{{- /* Content */ -}}
<div class="content" id="content">
{{- dict "Content" .Content "Ruby" $params.ruby "Fraction" $params.fraction "Fontawesome" $params.fontawesome | partial "function/content.html" | safeHTML -}}
<!-- 这里的版权声明是根据文章内容添加的，可删除 -->
{{- /*copyright*/ -}}
{{- $prestr := printf `<a href="%v" target="_blank" title="CC BY-NC-ND 4.0">%v</a>` .Site.Params.footer.license ( T "license" ) -}}
{{- $laststr := printf `<a href="%v" target="_blank">%v</a>` ($.Site.Author.link | default .Site.Home.RelPermalink) ( T "penname" ) -}}
{{- dict "preCopyRight" $prestr "afterCopyRight" $laststr | T "copyRightMsg" | safeHTML }}
</div>
{{- /* Comment */ -}}
{{- partial "comment.html" . -}}
</article>
{{- end -}}
类似的留言板页面可以使用默认的"page"类型。如果页面中有标题，同时不希望有目录，“关于”页面的模板更合适。或者使用头部参数toc: false禁用目录。
列表模板
列表页面是在文章的头部自定义参数，在模板中渲染。例如友链模板，参考LoveIt-extend/content/links/index.zh-cn.md。
头部参数需要按照yml文件的格式，注意不能用tab缩进。
links:
me:
name: 我
weight: 1
people:
- name: 朤尧
url: https://www.xiaodejiyi.com/
avatar: https://www.gravatar.com/avatar/ae94c8d8ca3d56eb035a3e62c2595150?s=240&d=mp
description: just do sth i should do.
friends:
name: 朋友
weight: 2
people:
links模板为：
<!-- links按照weight排序，排序后改变了原来的数组结构，相当于weight变为key值，其他数据组成value -->
{{- range $weight, $website := sort .Params.links "weight" -}}
<h3 id="{{ $website.name }}" tabindex="-1" style="outline: none;"><a href="#{{ $website.name }}"></a>{{ $website.name }}</h3>
<ul style="list-style: none;" id="firendLink">
{{- range $website.people -}}
<li>
<div class="box">
<div class="media">
<div class="media-left"><img src="{{ .avatar }}" width="55"></div>
<div class="media-content">
<i class="fa fa-user-ninja fa-fw"></i>
<!-- . 是 当前作用域 -->
{{ .name }} <i class="fa fa-link fa-fw"></i>
<a href="{{ .url }}" target="_blank">{{ .url }}</a>
<p>{{ .description }}</p>
</div>
</div>
</div>
</li>
{{- end -}}
</ul>
{{- end -}}
不过这里有一个Bug，content\links\index.zh-cn.md正文部分不能使用Markdown的标题标签或h1,h2...标签，否则前端目录代码会报错。
原因： links数组与文档内容分为两个部分，模板代码中，我只考虑了links数组，未考虑文中的h标签。生成的目录应只有links数组的标题，如果文章中出现标题，结果是：正常渲染，页面目录数组溢出。
如果你准备修复这个问题，可以参考：Table of Contents。然后修改layouts\links\single.html模板文件中的目录代码。
生成目录的代码：
<!-- 修改前的侧边目录 -->
<div class="details toc" id="toc-static" kept="{{ if $toc.keepStatic }}true{{ end }}">
<div class="details-summary toc-title">
<span>{{ T "contents" }}</span>
<span><i class="details-icon fas fa-angle-right"></i></span>
</div>
<div class="details-content toc-content" id="toc-content-static">
{{- dict "Content" .TableOfContents "Ruby" $params.ruby "Fraction" $params.fraction "Fontawesome" $params.fontawesome | partial "function/content.html" | safeHTML -}}
</div>
</div>
<!-- 修改后links的目录 -->
<div class="details toc" id="toc-static" kept="{{ if $toc.keepStatic }}true{{ end }}">
<div class="details-summary toc-title">
<span>{{ T "contents" }}</span>
<span><i class="details-icon fas fa-angle-right"></i></span>
</div>
<div class="details-content toc-content" id="toc-content-static">
<nav id="TableOfContents">
<ul>
{{- /* modify director */ -}}
{{- range $weight, $website := sort .Params.links "weight" -}}
{{- $groupName := dict "Content" $website.name "Ruby" $params.ruby "Fraction" $params.fraction "Fontawesome" $params.fontawesome | partial "function/content.html" | safeHTML -}}
<li><a href="#{{ $groupName }}">{{ $groupName }}</a></li>
{{- end -}}
</ul>
</nav>
</div>
</div>
问题不大，还能用。同理，可以使用列表模板制作说说，相册，视频页面，只是样式设计上不同。
分类模板
分类模板，需要考虑模板的渲染顺序，这个顺序很长，参考Hugo's Lookup Order，而且需要其他背景知识，如type的详细分类等等。
不过，按照以下步骤，你不需要深入研究这个复杂的顺序。
- 在
config.toml中配置分类
categories和tags为默认分类
[taxonomies]
# 左边单数，右边复数形式
category = "categories"
tag = "tags"
booklist = "booklist"
- 创建样例文章
在文章的头部参数中添加分类，注意要有中括号：
categories: ["demo1"]
tags: ["demo2"]
booklist: ["demo3"]
- 创建分类模板
首先要覆盖主题默认的分类模板，分析默认模板themes\LoveIt\layouts\taxonomy\list.html的代码：
...
{{- $taxonomy := .Data.Singular -}}
{{- if eq $taxonomy "category" -}}
<i class="far fa-folder-open fa-fw"></i> {{ .Title }}
{{- else if eq $taxonomy "tag" -}}
<i class="fas fa-tag fa-fw"></i> {{ .Title }}
{{- else -}}
{{- printf "%v - %v" (T $taxonomy | default $taxonomy) .Title -}}
{{- end -}}
...
可以发现，默认模板中包含了category,tag和其他，这三种模板。
所以覆盖需要将这个模板拆开，复制到博客的layouts目录下，分别命名为：categories,tags,taxonomy。内容上可以不修改，也可以将if语句剪枝。例如layouts\categories\list.html：
<h2 class="single-title animated pulse faster">
{{- $taxonomy := .Data.Singular -}}
{{- if eq $taxonomy "category" -}}
<i class="far fa-folder-open fa-fw"></i> {{ .Title }}
{{- end -}}
</h2>
覆盖之后，创建booklist分类的模板，复制categories分类的模板，修改为：
<h2 class="single-title animated pulse faster">
{{- $taxonomy := .Data.Singular -}}
{{- if eq $taxonomy "booklist" -}}
<i class="far fa-folder-open fa-fw"></i> {{ .Title }}
{{- end -}}
</h2>
是的，将if判断的category改为booklist，再换个Font Awesome图标。不要忘了还有layouts\booklist\terms.html也要改，同样修改if判断，改标题，改图标。
刷新界面，看看booklist分类有没有demo3的文章。如果没有，hugo server重新启动，现在应该有了。Hugo在这方面不能实时刷新。
- 首页文章增加分类
回到首页，你会发现，文章只有categories和tags的分类：demo1和demo2。添加demo3需要在themes\LoveIt\layouts\_default\summary.html中加入新的分类。
{{- $booklist := slice -}}
{{- range .Params.booklist -}}
{{- $category := partialCached "function/path.html" . . | printf "/booklist/%v" | $.Site.GetPage -}}
{{- $booklist = $booklist | append (printf `<a href="%v"><i class="fas fa-file-alt fa-fw"></i>%v</a>` $category.RelPermalink $category.Title) -}}
{{- end -}}
{{- with delimit $booklist " " -}}
<span class="post-category">
{{- . | safeHTML -}}
</span>
{{- end -}}
继续加其他分类，只需要再复制一段，用编辑器Ctrl+H替换代码中的booklist。
笔记页面
博客最初的设计是Hugo写文章，VuePress记笔记。在写这篇教程的过程中发现，如果把OneNote记的笔记放到VuePress上，再写文章，这会消耗大量时间。
不过VuePress能给文章加上一个背景知识。权衡之后放弃了VuePress。
如果你需要搭建一个笔记网站，可以考虑VuePress和Hugo的learn主题。
VuePress搭建过程可以参考B站教程和VuePress 中文文档。
搭建时需要注意这两点：
- Auto Sidebar插件自动生成侧边导航栏，如果没有这个插件，VuePress会繁琐得不想再用。
- 内置搜索只为页面的标题、h2、h3以及tags构建搜索索引。docsearch只支持技术文档，不支持博客索引和商业内容。Algolia搜索的方法可行，但是配置Algolia步骤很麻烦。
最后
博客搭建教程结束，如果你想要添加更多的功能，更灵活的开发自己的博客，那么学习Hugo框架吧！只是这需要投入一些成本，学习Hugo花了11个小时，开发又用了95个小时。或许你还需要了解下自媒体以及公众号，知乎等其他写作平台，这消耗了28个小时。（番茄工作法统计得出）
专心于博客的内容创作或许是更好的选择，希望这篇教程可以帮到你。
如果想学习Hugo，那么Hugo论坛是一个不错的地方。
我为什么要搭博客呢？把知识留下来！
