使用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>&nbsp;{{ .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 }}&nbsp;<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>&nbsp;{{ .Title }}

{{- else if eq $taxonomy "tag" -}}

    <i class="fas fa-tag fa-fw"></i>&nbsp;{{ .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>&nbsp;{{ .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>&nbsp;{{ .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 "&nbsp;" -}}

    &nbsp;<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论坛是一个不错的地方。

我为什么要搭博客呢？把知识留下来！

参考