87、【Ubuntu】【Hugo】搭建私人博客：侧边导航栏（一）

【声明】本博客所有内容均为个人业余时间创作，所述技术案例均来自公开开源项目（如Github，Apache基金会），不涉及任何企业机密或未公开技术，如有侵权请联系删除

背景

上篇 blog
【Ubuntu】【Hugo】搭建私人博客：TOC 配置&侧边导航栏

分析了 TOC 的配置，PaperMod 的设计理念，以及之前 custom.css 文件中自定义的行内代码颜色更改内容，下面继续

搭建私人博客

首先，上篇 blog 提到了自定义侧边导航栏，可以修改 layouts/ 中的模板文件 single.html，下面先来看 PaperMod 主题中的 single.html 模板

在 Hugo 中，single.html 模板用于渲染单篇内容页面，比如一篇博客文章，一篇文档，一个作品介绍等，简单来说，single.html 决定了当点开某一篇文章时，页面长什么样，每个 Hugo 主题下的 single.html 都不一样，single.html 决定了这个 Hugo 主题的风格是什么样的

Hugo 的模板系统使用不同类型的模板来生成不同类型的页面 ，除了刚才提到的 single.html 可以渲染单个内容项的详情页，还有比如 list.html 可以用来渲染列表页（比如首页，分类页，标签页等），像 single.html 和 list.html 等这样比较重要的模板文件，一般位于主题的默认路径，比如 PaperMod 的路径如下

Hugo 会按照模板查找顺序：

先找 /layouts/_default/single.html
再找 /themes/PaperMod/layouts/_default/single.html

优先使用全局模板，其次才到主题模板

下面来看下 PaperMod 的 single.html 模板

go 复制代码

{{- define "main" }}

<article class="post-single">
  <header class="post-header">
    {{ partial "breadcrumbs.html" . }}
    <h1 class="post-title entry-hint-parent">
      {{ .Title }}
      {{- if .Draft }}
      <span class="entry-hint" title="Draft">
        <svg xmlns="http://www.w3.org/2000/svg" height="35" viewBox="0 -960 960 960" fill="currentColor">
          <path
            d="M160-410v-60h300v60H160Zm0-165v-60h470v60H160Zm0-165v-60h470v60H160Zm360 580v-123l221-220q9-9 20-13t22-4q12 0 23 4.5t20 13.5l37 37q9 9 13 20t4 22q0 11-4.5 22.5T862.09-380L643-160H520Zm300-263-37-37 37 37ZM580-220h38l121-122-18-19-19-18-122 121v38Zm141-141-19-18 37 37-18-19Z" />
        </svg>
      </span>
      {{- end }}
    </h1>
    {{- if .Description }}
    <div class="post-description">
      {{ .Description }}
    </div>
    {{- end }}
    {{- if not (.Param "hideMeta") }}
    <div class="post-meta">
      {{- partial "post_meta.html" . -}}
      {{- partial "translation_list.html" . -}}
      {{- partial "edit_post.html" . -}}
      {{- partial "post_canonical.html" . -}}
    </div>
    {{- end }}
  </header>
  {{- $isHidden := (.Param "cover.hiddenInSingle") | default (.Param "cover.hidden") | default false }}
  {{- partial "cover.html" (dict "cxt" . "IsSingle" true "isHidden" $isHidden) }}
  {{- if (.Param "ShowToc") }}
  {{- partial "toc.html" . }}
  {{- end }}

  {{- if .Content }}
  <div class="post-content">
    {{- if not (.Param "disableAnchoredHeadings") }}
    {{- partial "anchored_headings.html" .Content -}}
    {{- else }}{{ .Content }}{{ end }}
  </div>
  {{- end }}

  <footer class="post-footer">
    {{- $tags := .Language.Params.Taxonomies.tag | default "tags" }}
    <ul class="post-tags">
      {{- range ($.GetTerms $tags) }}
      <li><a href="{{ .Permalink }}">{{ .LinkTitle }}</a></li>
      {{- end }}
    </ul>
    {{- if (.Param "ShowPostNavLinks") }}
    {{- partial "post_nav_links.html" . }}
    {{- end }}
    {{- if (and site.Params.ShowShareButtons (ne .Params.disableShare true)) }}
    {{- partial "share_icons.html" . -}}
    {{- end }}
  </footer>

  {{- if (.Param "comments") }}
  {{- partial "comments.html" . }}
  {{- end }}
</article>

{{- end }}{{/* end main */}}

下面来详细分析 single.html 模板

{``{- define "main" }} ... {``{- end }} ：Hugo 模板语法，表示定义一个名为 main 的模板块，这个块可以在其他模板中通过 {``{ template "main" . }} 被调用，结尾的 {``{ /* end main */ }} 是注释，说明这个 end 对应的是 main 块
<article class="post-single">：包裹整篇文章内容的 HTML 容器
<header class="post-header"> ：文章头部，里面有面包屑导航 {``{ partial "breadcrumbs.html" . }}（表示这里引入另一个模板），文章的标题是

html 复制代码

<h1 class="post-title entry-hint-parent">
  {{ .Title }}
  {{- if .Draft }}
    <!-- 如果是草稿，显示一个 SVG 图标 -->
  {{- end }}
</h1>

这里 <header class="post-header"> 的 <h1> 标题其实就是文章名

如果文章是草稿，也就是 .Draft == true

就会显示一个草稿图标（SVG 图标来自 Material Icons 风格），图标大概长这个样子

如果文章有描述 .Description，就显示描述

元信息（包括作者，日期，分类等）：

通过多个 partial（比如 post_meta.html，edit_post.html 等）引入
可通过配置参数 hideMeta: true 进行隐藏

封面图（Cover Image）

判断是否隐藏封面图（优先级：cover.hiddenInSingle > cover.hidden）
如果不隐藏的话，调用 cover.html 模板显示封面

go 复制代码

{{- $isHidden := (.Param "cover.hiddenInSingle") | default (.Param "cover.hidden") | default false }}
{{- partial "cover.html" (dict "cxt" . "IsSingle" true "isHidden" $isHidden) }}

目录（TOC），上篇 blog 【Ubuntu】【Hugo】搭建私人博客：TOC 配置&侧边导航栏介绍过了，在 hugo.toml 配置文件中启用 ShowToc = true，就会显示目录

go 复制代码

{{- if (.Param "ShowToc") }}
  {{- partial "toc.html" . }}
{{- end }}

文章正文，默认会对标题（h1~h6）自动添加锚点链接（方便分享某一小节），比如下面这样，可以看到点击标题旁边的 #，网站上会自动出现这里的锚点地址

这个选项默认是开启的，可通过 disableAnchoredHeadings: true 关闭此功能

html 复制代码

<div class="post-content">
  {{- if not (.Param "disableAnchoredHeadings") }}
    {{- partial "anchored_headings.html" .Content -}}
  {{- else }}{{ .Content }}{{ end }}
</div>

文章页脚 <footer class="post-footer">，有下面几个功能：

标签列表 ：遍历文章的 tags 并显示为链接
上下篇文章导航 ：如果 ShowPostNavLinks = true，就显示（后面再分析）
分享按钮 ：如果站点启用了 ShowShareButtons 并且文章未禁用（disableShare != true），则显示分享按钮

评论系统，如果文章设置了 comments = true，就加载评论模块

go 复制代码

{{- if (.Param "comments") }}
  {{- partial "comments.html" . }}
{{- end }}

OK，本篇先到这里，如有疑问，欢迎评论区留言讨论，祝各位功力大涨，技术更上一层楼！！！更多内容见下篇 blog