个人网站

Hugo&Stack主题的使用和装修记录

关于hugo日常使用的记录，包含归档、评论、搜索等

hugo官网|Stack官网

stack自带小部件：

Widgets | Stack

widgets:
        homepage:
            - type: search
            - type: archives
              params:
                  limit: 5
            - type: categories
              params:
                  limit: 10
            - type: tag-cloud
              params:
                  limit: 10

在stack的配置文件中，搜索工具、归档工具、分类和标签都是启用的。但是启用并不代表默认会出现，依然需要各种地方指定了值才能出现。

分类&标签

在你的内容文件的front matter中，需要指定tag的值和categories的值，我这里的front matter是toml格式

tag = ['hugo','stack']
categories = ["个人网站"]

归档：

需要在content/post目录下新建archives.md，内容如下，不需要任何正文内容

+++
title = 'Archives'
layout = "archives"
hidden = true
comments = false
+++

layout是指定为分类样式，hidden表示该文件不会被展示出来，comments表示评论区关闭.

其次，需要在 项目/layouts/_default 或者 主题/layouts/_default下存在archives.html，由于stack主题下默认就有这个文件，所以正常来说添加了archives.md就可以使用归档功能了。

搜索:

增加search.md

首先是同归档类似，需要在content/post目录下新建search.md，内容如下，不需要任何正文内容

+++
title = "search"
layout = "search"
hidden = true
comments = false
+++

增加搜索引擎的文件

静态网站的搜索本质上是将你的文档进行分词汇总到一个json文件，实际搜索的时候就是在搜索这个json文件。比较常用的是fuse.js,lunr.js或者主题自己封装的搜索能力。

  1. stack主题

    增加search.html和search.json

    需要在 项目/layouts/_default 或者 主题/layouts/_default 存在两个文件（对于stack来说），分别是search.html和search.json。

    在我clone的stack版本中，这两个文件在_default并不存在，但是在/layouts/page下面是有的，所以从cp layouts/page/* layouts/_default

    成功的话，会在public/post/search目录下生成index.html index.json两个文件，主要是index.json文件

  2. fuse

    我有看过两个文章是使用fuse的，但是我自己都没有实验成功，加上对hugo的模板还不熟，先不折腾了。

    给hugo添加搜索功能 | 搜百谷

    https://ttys3.dev/blog/hugo-fast-search

  3. Docsy主题

    可以参考官方文档Search | Docsy

修改总配置hugo.yaml

outputs:
  home:
    - HTML
    - JSON
  page:
    - HTML
    - JSON

这里home和page两种kind都配置的原因是:

假如你没有修改过总配置中的permalinks，那么你的博客的路径应该是 域名/p/文章名，这种情况下kind对应的是home类型

但是假如你像我一下修改了permalinks，比如我改成了 post: /:sections/:slug，这个是为了让我的博客地址以路径+文件名来显示，但是由于有了层级关系，里面的博客文章的kind就变成了page，因此在配置的时候，将home和page两个都指定是最好的

说实话，我其实还是不能理解这个kind的设计~

增加评论功能：

hugo支持许多评论框架，具体可以看hugo-comments|Comments | Stack，我选择的是

建议跟着快速上手 | Twikoo 文档去部署一遍，我这里选用的是Hugging Face免费部署的方案。

部署主要有两部分：一部分是生成一个mogodb的密钥串，二部分则是在hugging face上新建空间和项目，最终获得envId

然后修改站点配置文件

Gitalk

Gitalk本身就依赖的是github的issue功能，因此不需要额外部署；但是需要创建一个OAuthApp

     comments:
        enabled: true
        provider: gitalk
     twikoo:
        envId: https://你的项目空间.hf.space
        region:
        path:
        lang:
     gitalk:
        owner: github用户名
        admin: github用户名
        repo: 建议填博客项目，比如我的是qisiii.github.io
        clientID: OAuthApp创建得到
        clientSecret: OAuthApp创建得到

自定义博客的路径名：

slug:

一个正常的网址格式是下面这样的，其中路径的最后一段就是slug。

 <协议>://<主机名>/<路径>/<文件slug>?<查询字符串>#<片段>`

据说简短清晰的slug有助于SEO，但哪怕没有这个功能，我们的文件名很多时候也是中文的，经过编码后可读性太差。因此，设置一个简短的slug是很有必要的。

建议在模板文件archetypes/default.md直接新增slug字段，这样就不用每个文件手动添加了

+++
title = "{{ replace .Name "-" " " | title }}"
description = ""
date = {{ .Date }}
image = ""
draft = true
slug = "{{ replace .Name "-" " " | title }}"
+++

如果只设置slug，stack主题配置默认路径是 域名/p/slug这样子，其实对于文件的组织管理和展示路径依然不是很明朗，因此，我这里是以文件夹层级的方式生成路径。

在总配置中，修改或者新增

permalinks:
    post: /:sections/:slug

这里的:sections是指多个路径，但是hugo默认处理顶级目录会自动识别为section外，其他目录需要手动添加_index.md文件才行。

通过Github Action进行部署

我这里是将hugo目录作为一个私有项目，而public下文件的作为github.io的pages项目，因此等于是要将hugo的public文件部署到github.io的配置下；并且我还指定了自定义域名，所以要额外添加CNAME配置，不然每次执行action，都不会生成CNAME文件

name: GitHub Pages

on:
  push:
    branches:
      - master  # Set a branch to deploy
  pull_request:

jobs:
  deploy:
    runs-on: ubuntu-20.04
    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}
    steps:
      - uses: actions/checkout@v3
        with:
          submodules: true  # Fetch Hugo themes (true OR recursive)
          fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: '0.129.0'
          # 是否启用 hugo extend
          extended: true

      - name: Build
        run: hugo --minify

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        if: ${{ github.ref == 'refs/heads/master' }}
        with:
          PERSONAL_TOKEN: ${{ secrets.ACTION_TOKEN }}
          EXTERNAL_REPOSITORY: qisiii/qisiii.github.io  # 你的GitHub Pages仓库
          PUBLISH_BRANCH: master  # 或者是你的GitHub Pages分支
          PUBLISH_DIR: ./public
          commit_message: ${{ github.event.head_commit.message }}
          cname: custom.domain #这里填你配置页的自定义域名

基于 Github Action 自动构建 Hugo 博客 -

【Hugo网站搭建】GitHub Action自动化部署Hugo博客 | Eddy's blog

https://zenlian.github.io/github-actions-hugo/

标签云增加数量统计&归档页增加标签云:

Hugo Stack主题装修笔记

增加返回顶部按钮：

添加一键返回顶部功能 | Dlog

修改自己喜欢的指定按钮样式

.top-link {
    position: fixed;
    bottom: 30px;
    right: 30px;
    z-index: 99;
    background: #066fd1;
    width: 35px;
    height: 35px;
    align-items: center;
    justify-content: center;
    padding: 7px;
    border-radius: 5px;
    transition: visibility .5s, opacity .8s linear;
}

滚动到顶部时，需要隐藏置顶按钮，所以引用了jquery，处理逻辑

<a href="#top" aria-label="go to top"  class="top-link" id="top-link" accesskey="g" style="visibility: visible; opacity: 1;">
<svg  xmlns="http://www.w3.org/2000/svg"  width="24"  height="24"  viewBox="0 0 24 24"  fill="none"  stroke="currentColor"  stroke-width="2"  stroke-linecap="round"  stroke-linejoin="round"  class="icon icon-tabler icons-tabler-outline icon-tabler-chevron-up"><path stroke="none" d="M0 0h24v24H0z" fill="none"/><path d="M6 15l6 -6l6 6" /></svg>
</a>
<script src="https://apps.bdimg.com/libs/jquery/2.1.4/jquery.min.js"></script>
<script type="text/javascript">
      $(window).scroll(function(){
           if($(this).scrollTop()>300){
                $("#top-link").show()
           }else{
                $("#top-link").hide()
           }
      })
</script>

增加友链:

参考Hugo Stack主题装修笔记Part 2，结合自己的版本和主题略有修改

  1. 我的links.html是放在 layouts/_default下才有效，在layouts/page下面没起效

  2. data/json中指定的图片路径按博客所说需要放置在assets下再挂载到static中，我直接放在了static/link-img下

  3. 菜单-友链需要格外的配置，这里的路径是你对应的文件，我这里不是新建了一个friend文件夹，然后在下面再创建index.md,而是在post下直接创建了个friend.md

            - identifier: friends
          name: 友链|Friends
          url: /post/friends
          weight: 2
          params:
            icon: friends
            newTab: true

bing和google的收录：

bing 将 Github Pages 个人博客录入搜索引擎（以 Bing 为例） - RainbowC0 - 博客园

google Google搜索收录Github Pages（Blog可以被Google搜索到） | Marvin’s blog

图片支持放大查看~~

Hexo 折腾：利用 Fancybox 添加图片放大预览查看功能 | Tianma

网站添加favicon

截取成圆形图作物圈图像在线-最佳图像裁剪工具

添加Favicon到Hugo的网站中

通过githubWebHook通知服务器自动构建

使用 GitHub Webhook 实现静态网站自动化部署 · Jimmy Song

添加备案

在foot.customText:添加 '<a href="https://beian.miit.gov.cn/" target="_blank">京ICP备2023017017号-1</a>'

Hugo Stack
Licensed under CC BY-NC-SA 4.0
最后更新于 2024-10-18