使用Hugo框架搭建博客的过程

前言

最初在制作友链界面时，没有学习Hugo框架，一头雾水。网上有关的教程甚少，只能去学一遍Hugo。

在学习Hugo的过程中，了解了列表模板，分类模板。开发了几个功能页面，如：留言板，友链，记忆分类等。

本文介绍这些功能页面。

里程碑页面

首先需要了解头部参数type，通过type指定文章使用的模板类型，默认为page类型。
要注意特殊模板的文章放在一般content根目录下，模板放在layouts目录下。
里程碑界面依据themesLoveItlayoutspostssingle.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，contentlinksindex.zh-cn.md正文部分不能使用Markdown的标题标签或h1,h2...标签，否则前端目录代码会报错。

原因： links数组与文档内容分为两个部分，模板代码中，我只考虑了links数组，未考虑文中的h标签。生成的目录应只有links数组的标题，如果文章中出现标题，结果是：正常渲染，页面目录数组溢出。
如果你准备修复这个问题，可以参考：Table of Contents。然后修改layoutslinkssingle.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的详细分类等等。
不过，按照以下步骤，你不需要深入研究这个复杂的顺序。

1. 在config.toml中配置分类
   categories和tags为默认分类

[taxonomies]
    # 左边单数，右边复数形式
    category = "categories"
    tag = "tags"
    booklist = "booklist"

2. 创建样例文章
   在文章的头部参数中添加分类，注意要有中括号：

categories:		["demo1"]
tags:			["demo2"]
booklist:       ["demo3"]

3. 创建分类模板
   首先要覆盖主题默认的分类模板，分析默认模板themesLoveItlayouts axonomylist.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语句剪枝。例如layoutscategorieslist.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图标。不要忘了还有layoutsooklist erms.html也要改，同样修改if判断，改标题，改图标。
刷新界面，看看booklist分类有没有demo3的文章。如果没有，hugo server重新启动，现在应该有了。Hugo在这方面不能实时刷新。

4. 首页文章增加分类
   回到首页，你会发现，文章只有categories和tags的分类：demo1和demo2。添加demo3需要在themesLoveItlayouts\_defaultsummary.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 中文文档。

搭建时需要注意这两点：

1. Auto Sidebar插件自动生成侧边导航栏，如果没有这个插件，VuePress会繁琐得不想再用。
2. 内置搜索只为页面的标题、h2、h3以及tags构建搜索索引。docsearch只支持技术文档，不支持博客索引和商业内容。Algolia搜索的方法可行，但是配置Algolia步骤很麻烦。

最后

博客搭建教程结束，如果你想要添加更多的功能，更灵活的开发自己的博客，那么学习Hugo框架吧！只是这需要投入一些成本，学习Hugo花了11个小时，开发又用了95个小时。或许你还需要了解下自媒体以及公众号，知乎等其他写作平台，这消耗了28个小时。（番茄工作法统计得出）

专心于博客的内容创作或许是更好的选择，希望这篇教程可以帮到你。

如果想学习Hugo，那么Hugo论坛是一个不错的地方。

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

参考

• Hugo官方文档
• LoveIt-extend
• LoveIt Theme