不是从零开始的Hugo建站笔记

我不喜欢更不擅长写技术博客，这多半是我第一篇也是最后一篇技术博客，粗略记录一下我建站的过程。如果你对这个博客的任何地方感到好奇，希望这篇可以帮到你。

首先要特别特别特别感谢小球飞鱼 （不知道这是不是一个合适的昵称，链接里是ta的博客） ，我是在看到了ta的Hugo | 一起动手搭建个人博客吧才决定搭这个博客的，大部分装修改造也是参考了该博客里的教程，可以说没有ta就没有今天的我🙏

本地建站

请参考Hugo | 一起动手搭建个人博客吧以及Hugo官方教程。我一开始选用的主题是Diary，后来看到这个博客用的主题Stack我很喜欢就立刻换了，按照教程一步一步很快就可以看到一个博客在localhost:1313跑起来了。

（目前应该没有任何git commit or git push的指令）

部署到GitHub Pages

因为抠门不想买域名（其实也没几个钱），我选择直接用GitHub Pages，免费版的账户即可拥有，缺点之一是站点的repo必须是public（升级账户可以用private repo deploy pages）。

部署到GitHub Pages参考的是这个教程Create and host a blog with Hugo and GitHub Pages in less than 30 minutes，用一个public repo装静态代码（即Hugo project中的public文件夹）和一个private repo装源代码。因为教程是英文的，所以我自作主张稍微写一下中文版步骤。

手动部署到GitHub Page

首先在GitHub上创建一个public repository，命名为username.github.io（根据GitHub Pages，如果想用这个域名作为博客地址，repo必须命名为username.github.io)。这个repo会用来存放博客的静态文件，也就是hugo创建的public文件夹。

cd public
git init
git add remote origin username/username.github.io
git add .
git commit -m "init commit"
git push --set-upstream origin main

现在打开https://username.github.io，应该就可以看到和localhost:1313一样的内容了

自动部署

接下来创建一个另外的private repository（e.g. blog_source），用这个来存放原始文件，以及设置用于自动部署的GitHub Actions。GitHub Actions设置还参考了Hugo官方教程。

新建一个文件 .github/workflows/gh-pages.yml，内容是：

name: hugo CI

on:
  push:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}
    steps:
      - uses: actions/checkout@v2
        with:
          submodules: true 
          fetch-depth: 1   

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: 'latest'

      - name: Build
        run: hugo --minify

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          personal_token: ${{ secrets.PERSONAL_TOKEN }}
          external_repository: username/username.github.io # the public repo hosting website
          publish_branch: main # branch hosting the website
          publish_dir: ./public

不要忘了确认一下branch是main还是master！

先别急着push code，不过push了也没大问题，只是GitHub Actions会fail（然后会收到GitHub的邮件）。我们还需要设置一个GitHub Personal Token（而不能用官方教程中的GITHUB_TOKEN， I don’t know why）。设置好token以后，复制token，打开repo的页面，在settings里面的secrets添加这个token，保存。然后我们可以push code。

（如果博客没有修改的话，你会看到一个和刚才一模一样的页面，所以可以修改点啥比如新建一篇空的non-draft post再push）

cd .. # back to the root dir of hugo project
echo "public/" >> .gitignore
git init
git remote add origin https://github.com/username/blog_source.git
git add .
git commit -m "init"
git push --set-upstream origin main

之后我们都只需要向这个private repo里面push新增的内容或者修改，它会自动部署到负责host博客的public repo。

接下来可以搞装修了！装修可太好玩了！

装修之抄作业

我基本是对照着Hugo | 看中 Stack 主题的归档功能，搬家并做修改照抄的，简单列一下我都抄了哪些吧。

调整文章页面的显示样式
- 原主题在内容页面有目录(table of content/toc)的时候，左侧不会显示导航菜单，而是在左上角有一个‘Back’按钮，（参考主题demo页面）。修改后左侧仍然有菜单，右侧不管有没有目录都会显示归档以及标签的widgets。
- 思路就是新建了一个toc widget（新建文件是这个）然后改变了在_default/layouts/single.html中左右两侧side bars的显示逻辑（即这个文件中被注释掉的部分）
修改正文字号
- 因为我用的是submodule，没有修改任何在hugo-theme-stack文件夹内的文件，要override样式都得重新复制一个同路径的文件，于是我就偷懒了。我只在assets/scss/variables.scss改变了正文字号
删除 vibrant.js 插件
修改文章标题前提示块
增加网站 Icon 以及头像
- 两个图片文件都在static/img/中，在config.yaml中写路径的时候都要有开头的/，即/img/favicon.ico
修改网站字体
文章按年份分类
站点总字数统计
加入盘古之白
配置永久链接
文章评论Waline
- Stack主题本身是支持Waline的，但是它的config.yaml里的示范代码是错的，应该写成requiredMeta: ['nick', 'mail']的样式

装修之自己写

首页以外的文章卡片也显示description

Override了layouts/partials/article-list/compact.html ，在文章标题</h2>下增加了

<h2 class="article-title">
    {{- .Title -}}
</h2>
{{ with .Params.description }}
    <p>{{ . }}</p>
{{ end }}

Categories page

单个分类的名字/描述/颜色参考主题里的exampleSite/content/categories/里的文件。而显示分类的其实是一个单独的页面（也就是说它有自己的_index.md）。

content/categories/_index.md的内容：

---
title: "Categories"
date: 2019-05-28
layout: "categories" #这个是我用的自定义layout
slug: "categories"
menu: #菜单设置
    main:
        weight: -70
        params: 
            icon: hash
---

基于这个我又为这个页面创建了一个船新的layout。

新建一个文件layouts/_default/categories.html

{{ define "body-class" }}template-categories{{ end }}
{{ define "main" }}
    {{- $taxonomy := $.Site.GetPage "taxonomyTerm" "categories" -}}
    {{- $terms := $taxonomy.Pages -}}
    {{ if $terms }}
    <h2 class="section-title">{{ $taxonomy.Title }}</h2>
    <div class="subsection-list">
        {{ range $terms }}
            {{ partial "article-list/tile" (dict "context" . "size" "250x150" "Type" "taxonomy") }}
        {{ end }}
    </div>
    {{ end }}
    {{ partialCached "footer/footer" . }}
{{ end }}
{{ define "right-sidebar" }}
    {{ partial "sidebar/right.html" . }}
{{ end }}

折叠内容

我用的是Hugo的shortcode来实现的。新建layouts/shortcodes/toggle.html

<details>
    <summary>{{ (.Get 0) }}</summary>
    {{ .Inner | markdownify }}
</details>

用法

< toggle "用法" >
    在markdown里写下
< /toggle >

记得在<toggle>前后加上{{和}}，我没加是因为加了的话shortcode就会执行

Spotify Shortcode

新建layouts/shortcodes/spotify.html

<!--
Parameters:
    type - (Required) album / track / playlist / artist
    id - (Required) Target ID
    width - (Optional) width
    height - (Optional) height
-->

{{ if .IsNamedParams }}
<iframe src="https://open.spotify.com/embed/{{ .Get "type" }}/{{ .Get "id" }}"
    width="{{ default "100%" (.Get "width") }}"
    height="{{ default "380" (.Get "height") }}"
    frameborder="0"
    allowtransparency="true"
    allow="encrypted-media"></iframe>
{{ else }}
<iframe src="https://open.spotify.com/embed/{{ .Get 0 }}/{{ .Get 1 }}"
    width="{{ default "100%" (.Get 2) }}"
    height="{{ default "380" (.Get 3) }}"
    frameborder="0"
    allowtransparency="true"
    allow="encrypted-media"></iframe>
{{ end }}

用法：

< spotify type="track" id="2D3gvohUyOfXIVX6Mvhqae" height="80px">

记得在前后加上{{和}}，我没加是因为加了的话shortcode就会执行

示例：

隐藏的菜单栏

也许你看到过这个博客有一个奇怪的tab，它平时在导航菜单里看不到，里面的文章也不在Archives或者分类或者搜索结果里。如果你没看到，那也许有一天你会看到：）

首先要有一个单独的页面显示这个tab的内容，就会用到hugo的_index.md. 新建content/secret/_index.md

---
title: "Secret"
description: ""
menu:
    second:
        weight: 100
        params: 
            icon: letter-spacing
---

这个second是独立于main的另一个menu。我希望这个menu，只有在我打开这个tab里的内容的时候才会在侧边栏里显示，所以我们要override layouts/partials/sidebar/left.html这个文件。

先把它复制过来，尝试读懂它：菜单的显示逻辑是用range循环main menu里面的items。所以在这个range结束后再显示second menu的items，并且只有当前页面属于这个second menu的时候再显示就可以了。

{{ range .Site.Menus.main }}
	...
{{ end }}

{{ range .Site.Menus.second }}
      {{ $active := or (eq $currentPage.Title .Name) (or ($currentPage.HasMenuCurrent "second" .) ($currentPage.IsMenuCurrent "second" .)) }}
      {{ if $active}}
      <li {{ if $active }} class='current' {{ end }}>
          <a href='{{ .URL | relLangURL }}' {{ if eq .Params.newTab true }}target="_blank"{{ end }}>
              {{ $icon := default .Pre .Params.Icon }}
              {{ if .Pre }}
                  {{ warnf "Menu item [%s] is using [pre] field to set icon, please use [params.icon] instead.\nMore information: https://docs.stack.jimmycai.com/configuration/custom-menu.html" .URL }}
              {{ end }}
              {{ with $icon }}
                  {{ partial "helper/icon" . }}
              {{ end }}
              <span>{{- .Name -}}</span>
          </a>
      </li>        
      {{ end }}
{{ end }}

想要隐藏的文章或是subsection都一起放在content/secret/这个文件夹里。Stack主题本身即有一个hidden变量，在文章的front matter中加上这个hidden: true文章就不会在网站内出现，可以通过永久链接分享。

大概就这么多了。写技术博客也太难了吧。