Hugo on KukaDam

[Site] 将 Github Pages 个人博客录入搜索引擎（以 Bing 为例）

Fri, 31 Oct 2025 11:04:25 +0800

参考将 Github Pages 个人博客录入搜索引擎（以 Bing 为例） - RainbowC0 - 博客园即可，但是还是为自己留档稍微写写

目前百度不再允许导入 gitee.io 和 github.io 等一级域名的网站，理由是这些域名满额了

添加网站

打开Bing Webmaster Tools，并登录。可以选择三种登录账号：Google、Microsoft、Facebook，这里我用 Microsoft 账号登录。
第一次登录会提升添加网站，如果已经通过GSC，可以用GSC。这里我手动添加，直接复制博客主页的URL粘贴即可

验证网站

有三个验证方式：文件、标签、CNAME ，这里选择文件验证（第一个）

点击 BingSiteAuth.xml 下载验证文件，然后上传到 Github Page 的根目录下，再更新 Github Page 部署，这样个人博客就被更新了，可以访问网站根目录下找到 BingSiteAuth.xml。
**注意：如果是用 Hugo 构建的网站，需要把验证文件放到项目的 static 文件夹下，然后运行 hugo 重新生成网页并上传。**然后点击“验证”即可。

添加网站地图

点击网站地图

用 Hugo 生成的博客网站会自带 sitemap.xml 文件，通常放在网站根目录下，点击“提交网站地图”，输入 https://博客主页URL/sitemap.xml，然后提交。

验证成功

最后可以用搜索引擎尝试搜一下自己的博客网站看看有没有结果，对于其他搜索引擎大体也是如此。

[Hugo] Hugo部署到Vercel

Thu, 30 Oct 2025 20:25:25 +0800

部署到Vercel

因为我的博客是已经部署在 github page 上的，所以已经有了源码仓库和公开仓库。

一般来说白嫖博客在github page上部署结束就可以了，具体可以参考【Hugo】Hugo + Github 免费部署自己的博客。但是考虑到后续的管理，还是打算在Vercel上也部署。

Hugo官方的文档【Host on Vercel】其实已经比较详细了，按照他的步骤来就行，只不过是英文的看起来比较费劲。

准备

创建并登录 GitHub 账号
创建仓库并在本地初始化。（因为我已经有了就不细说）
使用Github授权登录Vercel

添加文件

在博客主文件夹添加 vercel.json 和 build.sh 文件，具体可参考Hugo官方文档。
这个 JSON 文件告诉 Vercel 如何构建你的站点（指定构建命令和输出目录）。

1// vercel.json
2{
3  "$schema": "https://openapi.vercel.sh/vercel.json",
4  "buildCommand": "chmod a+x build.sh && ./build.sh",
5  "outputDirectory": "public"
6}

这个 Bash 脚本在 Vercel 环境中安装 Hugo、Go、Node.js 和 Dart Sass，然后构建站点。复制整个脚本。要注意替换成你博客所用的hugo版本，可以在博客主文件夹打开命令行，运行 hugo version 查看

 1# build.sh
 2#!/usr/bin/env bash
 3
 4#------------------------------------------------------------------------------
 5# @file
 6# Builds a Hugo site hosted on Vercel.
 7#
 8# The Vercel build image automatically installs Node.js dependencies.
 9#------------------------------------------------------------------------------
10
11main() {
12
13  DART_SASS_VERSION=1.93.2
14  GO_VERSION=1.25.3
15  HUGO_VERSION=0.152.0 # 这里记得替换成自己的版本
16  NODE_VERSION=22.20.0
17
18  export TZ=Europe/Oslo
19
20  # Install Dart Sass
21  echo "Installing Dart Sass ${DART_SASS_VERSION}..."
22  curl -sLJO "https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
23  tar -C "${HOME}/.local" -xf "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
24  rm "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
25  export PATH="${HOME}/.local/dart-sass:${PATH}"
26
27  # Install Go
28  echo "Installing Go ${GO_VERSION}..."
29  curl -sLJO "https://go.dev/dl/go${GO_VERSION}.linux-amd64.tar.gz"
30  tar -C "${HOME}/.local" -xf "go${GO_VERSION}.linux-amd64.tar.gz"
31  rm "go${GO_VERSION}.linux-amd64.tar.gz"
32  export PATH="${HOME}/.local/go/bin:${PATH}"
33
34  # Install Hugo
35  echo "Installing Hugo ${HUGO_VERSION}..."
36  curl -sLJO "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
37  mkdir "${HOME}/.local/hugo"
38  tar -C "${HOME}/.local/hugo" -xf "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
39  rm "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
40  export PATH="${HOME}/.local/hugo:${PATH}"
41
42  # Install Node.js
43  echo "Installing Node.js ${NODE_VERSION}..."
44  curl -sLJO "https://nodejs.org/dist/v${NODE_VERSION}/node-v${NODE_VERSION}-linux-x64.tar.xz"
45  tar -C "${HOME}/.local" -xf "node-v${NODE_VERSION}-linux-x64.tar.xz"
46  rm "node-v${NODE_VERSION}-linux-x64.tar.xz"
47  export PATH="${HOME}/.local/node-v${NODE_VERSION}-linux-x64/bin:${PATH}"
48
49  # Verify installations
50  echo "Verifying installations..."
51  echo Dart Sass: "$(sass --version)"
52  echo Go: "$(go version)"
53  echo Hugo: "$(hugo version)"
54  echo Node.js: "$(node --version)"
55
56  # Configure Git
57  echo "Configuring Git..."
58  git config core.quotepath false
59  if [ "$(git rev-parse --is-shallow-repository)" = "true" ]; then
60    git fetch --unshallow
61  fi
62
63  # Build the site
64  echo "Building the site"
65  hugo --gc --minify --baseURL "https://${VERCEL_PROJECT_PRODUCTION_URL}"
66
67}
68
69set -euo pipefail
70main "$@"

创建完后还要提交推送到仓库上

创建项目

打开Vercel，点击 Add New 添加项目 Project

安装Vercel应用，选择博客的主仓库（一般是私密的）

点击导入 Import

修改项目名和框架名后，点击部署 Deploy

等待成功后出现界面：

后续

页面没有文章

文章在发布时设置了 draft = true ，Hugo 默认不构建 draft=true 的文章 → public/ 目录中没有 .html 文件 → 页面为空！

但在 GitHub Pages 正常显示，但 Vercel 却不显示，这说明不是 draft 的问题。

查看之前部署在 github page 上的的工作流文件 .github/workflows/hugo_deploy.yaml

 1name: deploy
 2
 3# 代码提交到main分支时触发github action
 4on:
 5  push:
 6    branches:
 7      - main
 8
 9jobs:
10  deploy:
11    runs-on: ubuntu-latest
12    steps:
13        - name: Checkout
14          uses: actions/checkout@v4
15          with:
16              fetch-depth: 0
17
18        - name: Setup Hugo
19          uses: peaceiris/actions-hugo@v3
20          with:
21              hugo-version: 0.152.0
22              extended: true
23
24        - name: Build Web
25          run: hugo -D
26
27        - name: Deploy Web
28          uses: peaceiris/actions-gh-pages@v4
29          with:
30              PERSONAL_TOKEN: ${{ secrets.TOKEN }}
31              EXTERNAL_REPOSITORY: bobQAQ003/Kuka
32              PUBLISH_BRANCH: main
33              PUBLISH_DIR: ./public
34              commit_message: auto deploy

hugo -D 构建时会包含草稿，而部署在 Vercel上的网页生成不包含 draft ，可以修改成：

1  # Build the site
2  echo "Building the site"
3  hugo --gc --minify --baseURL "https://${VERCEL_PROJECT_PRODUCTION_URL}"
4  hugo --gc --minify --buildDrafts --baseURL "https://${VERCEL_PROJECT_PRODUCTION_URL}"

再推送到github上

既然是不编译的问题，那么也可以把每篇文章的draft = true 改为 false ，不修改 build.sh，这样应该也是可以。

修改域名

点击 Domains ，再点击 Edit

因为没有申请域名，所以修改的时候不能随便修改，保留.vercel.app 前缀找个合适的保存就行。后续申请了域名再仔细考虑这个，现在进行修改只是为了方便记住。

[Hugo] 自定义加载动画

Tue, 28 Oct 2025 17:27:50 +0800

引入这个动画是因为加载自定义字体后，因为字体太大导致网站总是先显示默认字体，过一会再显示自定义字体，~~强迫症犯了~~。所以希望等加载后再展示网站

牛顿摆动画

将以下代码复制进layouts/partials/head/custom.html(文件不存在则自行创建)

  1<div class="loading">
  2    <!-- html内容 -->
  3    <div class="newtons-cradle">
  4        <div class="newtons-cradle__dot"></div>
  5        <div class="newtons-cradle__dot"></div>
  6        <div class="newtons-cradle__dot"></div>
  7        <div class="newtons-cradle__dot"></div>
  8    </div>
  9</div>
 10
 11<style>
 12    .loading {
 13        position: fixed;
 14        display: flex;
 15        justify-content: center;
 16        align-items: center;
 17        top: 0;
 18        left: 0;
 19        width: 100%;
 20        height: 100%;
 21        z-index: 99;
 22        background-color: #f5f5fa;
 23    }
 24	
 25    /* css内容 */
 26
 27    /* From Uiverse.io by dovatgabriel */ 
 28    .newtons-cradle {
 29        --uib-size: 50px;
 30        --uib-speed: 1.2s;
 31        --uib-color: #474554;
 32        position: relative;
 33        display: flex;
 34        align-items: center;
 35        justify-content: center;
 36        width: var(--uib-size);
 37        height: var(--uib-size);
 38    }
 39
 40    .newtons-cradle__dot {
 41        position: relative;
 42        display: flex;
 43        align-items: center;
 44        height: 100%;
 45        width: 25%;
 46        transform-origin: center top;
 47    }
 48
 49    .newtons-cradle__dot::after {
 50        content: '';
 51        display: block;
 52        width: 100%;
 53        height: 25%;
 54        border-radius: 50%;
 55        background-color: var(--uib-color);
 56    }
 57
 58    .newtons-cradle__dot:first-child {
 59        animation: swing var(--uib-speed) linear infinite;
 60    }
 61
 62    .newtons-cradle__dot:last-child {
 63        animation: swing2 var(--uib-speed) linear infinite;
 64    }
 65
 66    @keyframes swing {
 67        0% {
 68            transform: rotate(0deg);
 69            animation-timing-function: ease-out;
 70        }
 71
 72        25% {
 73            transform: rotate(70deg);
 74            animation-timing-function: ease-in;
 75        }
 76
 77        50% {
 78            transform: rotate(0deg);
 79            animation-timing-function: linear;
 80        }
 81    }
 82
 83    @keyframes swing2 {
 84        0% {
 85            transform: rotate(0deg);
 86            animation-timing-function: linear;
 87        }
 88
 89        50% {
 90            transform: rotate(0deg);
 91            animation-timing-function: ease-out;
 92        }
 93
 94        75% {
 95            transform: rotate(-70deg);
 96            animation-timing-function: ease-in;
 97        }
 98    }
 99
100    .animated-stop {
101        animation-play-state: paused !important;
102    }
103
104    .scaleAndFadeout {
105        animation: scaleAndFadeOut 1.5s forwards;
106    }
107
108    /** 放大1.5倍，并渐变到透明 */
109    @keyframes scaleAndFadeOut {
110        0% {
111            transform: scale(1);
112            opacity: 1;
113        }
114        100% {
115            transform: scale(1.5);
116            opacity: 0;
117        }
118    }
119
120</style>
121
122<script>
123    // 首次加载：等资源完 → 播放动画 → 淡出
124    window.addEventListener('load', () => {
125        const loading = document.querySelector('.loading');
126        if (!loading) return;
127
128        setTimeout(() => loading.classList.add('scaleAndFadeout'), 600);
129        setTimeout(() => loading.style.display = 'none', 2000);
130    });
131
132    // PJAX 切换：直接隐藏
133    document.addEventListener('pjax:complete', () => {
134        const loading = document.querySelector('.loading');
135        if (loading) loading.style.display = 'none';
136    });
137</script>

这边设置的是第一次进入界面和手动刷新时会加载动画

自定义动画

前往UIverse，找一个加载动画
将加载动画的html，css分别根据下面的模板填写，然后将内容复制到layouts/partials/head/custom.html

 1<div class="loading">
 2    <!-- html内容 -->
 3</div>
 4
 5<style>
 6    .loading {
 7        position: fixed;
 8        display: flex;
 9        justify-content: center;
10        align-items: center;
11        top: 0;
12        left: 0;
13        width: 100%;
14        height: 100%;
15        z-index: 99;
16        background-color: #f5f5fa;
17    }
18	
19    .animated-stop {
20        animation-play-state: paused !important;
21    }
22
23    .scaleAndFadeout {
24        animation: scaleAndFadeOut 1.5s forwards;
25    }
26    
27    /** 放大1.5倍，并渐变到透明 */
28    @keyframes scaleAndFadeOut {
29        0% {
30            transform: scale(1);
31            opacity: 1;
32        }
33        100% {
34            transform: scale(1.5);
35            opacity: 0;
36        }
37    }
38    
39    /* css内容 */
40</style>
41
42<script>
43    // 首次加载：等资源完 → 播放动画 → 淡出
44    window.addEventListener('load', () => {
45        const loading = document.querySelector('.loading');
46        if (!loading) return;
47
48        setTimeout(() => loading.classList.add('scaleAndFadeout'), 600);
49        setTimeout(() => loading.style.display = 'none', 2000);
50    });
51
52    // PJAX 切换：直接隐藏
53    document.addEventListener('pjax:complete', () => {
54        const loading = document.querySelector('.loading');
55        if (loading) loading.style.display = 'none';
56    });
57</script>

具体的细节可以根据需求更改

样式

CSS可能用到样式

 1/**
 2 * 可能会用到的CSS
 3 */
 4{
 5    /* 整体修改元素大小(大于1放大, 小于1缩小) */
 6    zoom: 1.0;
 7
 8    /* 开始动画播放 */
 9    animation-play-state: running;
10
11    /* 暂停动画播放 */
12    animation-play-state: paused;
13
14    /* 元素居中(flex布局) */
15    display: flex;
16    justify-content: center;
17    align-items: center;
18
19    /* 元素隐藏 */
20    display: none;
21
22    /* 定义动画 */
23    @keyframes 动画名 {
24        0% {}
25        进度% {}
26        100% {}
27    }
28
29    /* 执行动画 */
30    animation: 动画名 时间;
31}

CSS动画常用参数

 1/**
 2 * CSS动画常用参数
 3 */
 4{
 5     /* 不透明度 */
 6    opacity: 1;
 7
 8    /* 放大缩小 */  
 9    transform: scale(1);
10
11    /* 旋转 */
12    transform: rotate(360deg);
13
14    /* 平移(水平, 垂直) */
15    transform: translate(-100%, 0);
16}

[Hugo] 美化过程中遇到的问题

Sat, 25 Oct 2025 09:40:08 +0800

引入PJAX

从 MoOx/pjax（不带JQuery）这里引入
我们需要刷新的是左侧边栏 ，右侧边栏 和中间的内容

从源代码可以发现这些元素都被一个<div class="main-container">...</div>包裹着
根据官方文档，在layouts/partials/footer/custom.html加入以下代码来引入PJAX：

1<!-- 【custom.html】 -->
2<script src="https://cdn.jsdelivr.net/npm/pjax/pjax.min.js"></script>
3<script>
4    var pjax = new Pjax({
5        selectors: [
6            ".main-container"
7        ]
8    })
9</script>

我这里先创建layouts/partials/footer/pjax.html，再在custom.html里引用

 1<!-- pjax.html -->
 2<script src="https://cdn.jsdelivr.net/npm/pjax/pjax.min.js"></script>
 3<script>
 4    var pjax = new Pjax({
 5    selectors: [
 6      ".main-container",
 7    ]
 8  })
 9</script>
10
11<!-- custom.html -->
12{{partial "footer/pjax.html"}}

文章样式修复

问题描述：
- 引入pjax后，重启hugo server -D，发现文章样式丢失，手动点击刷新可以恢复

产生原因：
- <body>标签中的class名缺失article-page，导致文章样式丢失

解决思路：
- 通过官方提供了数据预处理方法，来预处理数据，获取到新页面的className，然后我们手动将这className设置到<body>上
具体步骤：
修改layouts/partials/footer/pjax.html，（如果是在custom.html加了pjax就在那里改）引入以下代码：

 1<script>
 2    pjax._handleResponse = pjax.handleResponse;
 3    pjax.handleResponse = function(responseText, request, href, options) {
 4        if (request.responseText.match("<html")) {
 5            if (responseText) {
 6                // 将新页面的html字符串解析成DOM对象
 7                let newDom = new DOMParser().parseFromString(responseText, 'text/html');
 8                // 获取新页面中body的className，并设置回当前页面
 9                let bodyClass = newDom.body.className;
10                document.body.setAttribute("class", bodyClass)
11            }
12            // 放行，交给pjax自己处理
13            pjax._handleResponse(responseText, request, href, options);
14        } else {
15            // handle non-HTML response here
16        }
17    }
18</script>

主题切换修复

问题描述：
- 切换页面后，左下角切换主题颜色按钮不生效

产生原因：
- 在Stack主题源码assets/ts/colorScheme.ts中，脚本初始化时，会给元素绑定一个点击事件。但因为页面切换了，替换了该元素，但该元素没有重新绑定点击事件，导致点击主题切换失效

解决思路：
- 在PJAX切换完页面后，重新执行一遍colorScheme.ts的初始化，使元素重新绑定点击事件
- 而colorScheme.ts被main.ts引用，在main.ts中执行了初始化，并且main.ts生成了全局变量 Stack
- 所以在PJAX执行完后，使用全局变量 Stack ，执行里面的初始化方法，重新执行一遍脚本，来绑定点击事件
- PJAX官方文档也提供了PJAX执行完后的事件pjax:complete，监听这个事件，Stack 执行初始化就好
具体步骤：
- 修改layouts/partials/footer/pjax.html，引入以下代码

1<script>
2    document.addEventListener('pjax:complete', () => {
3        // Stack脚本初始化
4        window.Stack.init();
5    })
6</script>

文章搜索修复

问题描述：
- 使用文章搜索功能时，输入关键词，无任何搜索记录
产生原因：
- 查看assets/ts/search.tsx文件，情况和上面的colorScheme.ts类似，存在绑定事件

解决思路：
- 把 search.tsx 初始化内容封装为一个函数，并把函数 export 出来
- 由 main.ts 引入这个函数，并放到 Stack.init() 的方法中，利用此方法来重新初始化搜索脚本

具体步骤：
修改assets/ts/search.tsx代码，封装方法并export

 1/**
 2 * 把window.addEventListener('load' ...这部分代码注释掉
 3 * 初始化工作交给Stack.init()处理了，不需要这个了
 4 */  
 5...
 6function searchInit() {
 7    let search = document.querySelector('.search-result');
 8    if (search) {
 9        const searchForm = document.querySelector('.search-form') as HTMLFormElement,
10            searchInput = searchForm.querySelector('input') as HTMLInputElement,
11            searchResultList = document.querySelector('.search-result--list') as HTMLDivElement,
12            searchResultTitle = document.querySelector('.search-result--title') as HTMLHeadingElement;
13
14        new Search({
15            form: searchForm,
16            input: searchInput,
17            list: searchResultList,
18            resultTitle: searchResultTitle,
19            resultTitleTemplate: window.searchResultTitleTemplate
20        });
21    }
22}
23
24export {
25    searchInit
26}

修改assets/ts/main.ts，引入搜索初始化方法并调用

1...
2import { searchInit } from "ts/search";
3let Stack = {
4    init: () => {
5        ...
6        // 调用search脚本初始化方法
7        searchInit();
8    }
9}

从Stack模板文件复制layouts\partials\footer\components\script.html，把"JSXFactory" "createElement"补充，改法参考layouts\page\search.html，

搜索内容跳转修复

问题描述：
- 能进行搜索，但搜索出来的内容并没有被PJAX识别到，导致PJAX没有拦截，进而导致页面刷新
产生原因：
- 阅读 search.tsx 源码可知，搜索内容的数据，是通过 React.render() 动态渲染回页面的，这些动态数据没有被PJAX识别到

解决思路：
- PJAX官方文档提供给了重新解析数据的方法，所以在 React.render() 之后，调用PJAX方法，重新解析页面即可
具体步骤：
修改assets/ts/search.tsx，在动态渲染数据方法末尾让pjax重新解析文档

1private async doSearch(keywords: string[]) {
2    ...
3    /* 
4    方法末尾，让pjax重新解析文档数据，识别动态渲染的数据
5    虽然当前文件没有pjax对象，但最后静态页面会生成一个整体的js文件
6    pjax对象那时就能识别到，就可成功调用
7    */
8    pjax.refresh(document);
9}

KaTeX修复

KaTex渲染失效

问题描述：
- 含有 数学公式(KaTeX) 的文章，里面的数学公式不能正常渲染出来
产生原因：
- 阅读源码layouts/partials/article/components/math.html，KaTeX渲染公式需要执行renderMathInElement，而PJAX的无刷新技术无法触发DOMContentLoaded的监听

解决思路：
- 将renderMathInElement封装为函数，交由PJAX加载结束后执行
具体操作：
修改layouts/partials/article/components/math.html，添加一个元素标签，便于判断文档是否使用了KaTeX

1...
2<div class="math-katex"></div>

layouts/partials/footer/pjax.html，引入以下代码

 1<script>
 2    async function renderKaTeX() {
 3        // 判断当前页面是否有KateX
 4        let katex = document.querySelector(".math-katex");
 5        if (!katex) {
 6            return;
 7        }
 8        // 等待函数加载成功后，再执行渲染方法
 9        while (typeof renderMathInElement !== 'function') {
10            await delay(500);
11        }        
12        // KaTeX渲染方法
13        renderMathInElement(document.body, {
14            delimiters: [
15                { left: "$$", right: "$$", display: true },
16                { left: "$", right: "$", display: false },
17                { left: "\\(", right: "\\)", display: false },
18                { left: "\\[", right: "\\]", display: true }
19            ],
20            ignoredClasses: ["gist"]
21        });
22    }
23    
24    /**
25     * 同步延迟
26     */
27    function delay(time) {
28        return new Promise(resolve => {
29            setTimeout(resolve, time)
30        })
31    }
32
33    document.addEventListener('pjax:complete', () => {
34        renderKaTeX();
35    })
36</script>

引用块和公式块冲突

问题描述：
- 在引用块中又写了公式块，最终渲染出这样：
产生原因：
- Typora 内置的 Markdown 解析器 先合并 blockquote 行、再交给 MathJax，所以Typora显示正常
- 而 Hugo（Goldmark 解析器）逐行解析，每一行前面都带着 >，于是 Goldmark 把 > 转义成 > 塞进公式节点，KaTeX 收到的是：> \mu(z_t) = 0.8 \quad (...)
解决思路：
- 目前没有很好的解决方法，只能是避免混用

浏览量统计失效

问题描述：
- 先前使用的vercount在引入Pjax后失效，必须手动刷新才会生效
产生原因：
- 原始的Vercount脚本在页面第一次加载时执行，它会在页面中插入浏览量显示的元素。但是当使用Pjax加载x新页面时，脚本不会自动重新执行，因此新页面中的浏览量元素没有被插入。
解决思路：
- 动态重新加载脚本，移除旧脚本，清除之前的执行状态，
- 创建新脚本，等待 pjax:complete 完成后再添加到 DOM 中
具体步骤：
layouts/partials/footer/pjax.html，引入代码

 1<script>
 2    // 浏览量统计
 3    function initVerCount() {
 4        // 移除已存在的 Vercount 脚本
 5        const existingScript = document.querySelector('script[src="https://cn.vercount.one/js"]');
 6        if (existingScript) {
 7            existingScript.remove();
 8        }
 9
10        // 创建新的 Vercount 脚本
11        const newScript = document.createElement('script');
12        newScript.src = 'https://cn.vercount.one/js';
13        newScript.defer = true;
14
15        // 添加到 head 中
16        document.head.appendChild(newScript);
17    }
18    
19    document.addEventListener('pjax:complete', () => {
20        ...
21        initVerCount();
22    })
23</script>

网站标题更改

问题描述：
- 使用了PJAX后，点击左侧边栏和文章，网站标题都是你在.yaml中设置的languages.zh-cn.title，当你手动刷新才会变成相关页面

产生原因：
- PJAX 通过 AJAX 加载新页面的内容（这里配置的 selectors: [".main-container"]，只替换主容器），而不进行完整的页面重载（full page reload）。这意味着title部分没有进行更新。
解决思路：
- 在 handleResponse 函数中添加逻辑：从新页面的 HTML 响应中提取 <title>标签，设置到document.title
具体步骤：
在\layouts\partials\footer\pjax.html中修改文章格式的同时，添加title

 1<script>
 2    // pjax刷新区域
 3    var pjax = new Pjax({
 4    selectors: [
 5        ".main-container",
 6    ]
 7    })
 8
 9    // 修正文章样式丢失
10    pjax._handleResponse = pjax.handleResponse;
11    pjax.handleResponse = function(responseText, request, href, options) {
12        if (request.responseText.match("<html")) {
13            // 将新页面的html字符串解析成DOM对象
14            let newDom = new DOMParser().parseFromString(responseText, 'text/html');
15            
16            // 1. 更新 body class，获取新页面中body的className，并设置回当前页面
17            let bodyClass = newDom.body.className;
18            document.body.setAttribute("class", bodyClass)
19
20            // 2. 更新 <title>
21            let newTitle = newDom.querySelector('title');
22            if (newTitle && newTitle.textContent) {
23                document.title = newTitle.textContent.trim();
24            }
25
26            pjax._handleResponse(responseText, request, href, options);
27        } else {
28            // handle non-HTML response here
29        }
30    }
31...
32</script>

进度条加载

问题描述：
- 使用了PJAX后，原先采用的进度条失效，采用另外的方法
具体步骤：
前往【topbar】下载zip包，将解压后的 topbar.min.js 放到assets\js\topbar.min.js
通过监听PJAX两个事件 pjax:send 和 pjax:complete 实现伪进度条
layouts/partials/footer/pjax.html，引入代码

 1{{ with resources.Get "js/topbar.min.js" }}
 2    <!-- 引入本地JS脚本 -->
 3    <script src={{ .Permalink }}></script>
 4{{ end }}
 5<script>
 6    // 修改进度条颜色
 7    topbar.config({
 8        barColors: {
 9            '0': 'rgba(255,  255, 255, 1)', // 进度0%白色
10            '1.0': 'rgba(0, 149, 234,  1)' // 进度100%蓝色
11        }
12    })
13	
14    document.addEventListener('pjax:send', () => {
15        // 显示顶部进度条
16        topbar.show();
17    })
18	
19    document.addEventListener('pjax:complete', () => {
20        ....
21        // 隐藏顶部进度条
22        topbar.hide();
23    })
24</script>

[Hugo] Hugo美化

Fri, 24 Oct 2025 19:19:24 +0800

为避免踩坑，凡是需要更改的文件都从themes/主题复制到主目录下，个性化配置文件建议都在博客主目录下操作，减少更新主题时个性化配置被覆盖的麻烦。

每次服务启动，会同步更新所有位置配置文件，但主目录配置文件优先级最高

yaml配置

添加行号后复制代码会带有行号

参考小白hugo博客装修笔记（2）- B1ain’s Blog

手动复制有行号

在/assets/scss/custom.scss 文件中添加如下内容，将行号设定为不可选中

1// 手动复制禁止复制行号
2.highlight .ln {
3  user-select: none;
4}

copy按钮复制带行号

修改/themes/hugo-theme-stack/assets/ts/main.ts文件中的复制按钮逻辑。

但具体情况是，在本地进行调试时，确实手动复制和copy复制都会涉及行号。当部署到github pages打开后，copy不会有影响，反而手动复制可能会复制到行号。

所以具体情况看个人博客部署情况吧。~~反正能用~~，若要修改参考 Hugo-stackの美化

具体修改assets/ts/main.ts

 1highlights.forEach(highlight => {
 2    const copyButton = document.createElement('button');
 3    copyButton.innerHTML = copyText;
 4    copyButton.classList.add('copyCodeButton');
 5    highlight.appendChild(copyButton);
 6
 7    const codeBlock = highlight.querySelector('code[data-lang]');
 8    if (!codeBlock) return;
 9
10    copyButton.addEventListener('click', () => {
11        // 创建一个临时容器来克隆代码块的内容
12        const tempCodeBlock = codeBlock.cloneNode(true) as HTMLElement;
13
14        // 删除行号，行号的元素是 <span class="ln">
15        const lineNumbers = tempCodeBlock.querySelectorAll('.ln');
16        lineNumbers.forEach(lineNumber => lineNumber.remove());
17
18        // 获取没有行号的纯文本内容
19        const codeText = tempCodeBlock.textContent;
20
21        navigator.clipboard.writeText(codeText || '')
22        // navigator.clipboard.writeText(codeBlock.textContent)
23            .then(() => {
24                copyButton.textContent = copiedText;
25
26                setTimeout(() => {
27                    copyButton.textContent = copyText;
28                }, 1000);
29            })
30            .catch(err => {
31                alert(err)
32                console.log('Something went wrong', err);
33            });
34    });
35});

左边栏副标题换行

参考 Hugo-stackの美化 II

找到 layouts/partials/sidebar/left.html，复制到博客的同名主文件夹下：

1<div class="site-meta">
2    <h1 class="site-name"><a href="{{ .Site.BaseURL | relLangURL }}">{{ .Site.Title }}</a></h1>
3    <h2 class="site-description">{{ .Site.Params.sidebar.subtitle }}</h2>
4    <h2 class="site-description">{{ .Site.Params.sidebar.subtitle | safeHTML }}</h2>
5</div>

当然也可以修改stack模板下hugo-theme-stack里的文件，~~但不建议~~，毕竟还要通过源码进行学习。

然后在 hugo.yaml 中在要换行的地方加上 <br>：

 1languages:
 2    en:
 3        languageName: English
 4        title: Example Site
 5        weight: 1
 6        params:
 7            sidebar:
 8                subtitle: Example description
 9    zh-cn:
10        languageName: 中文
11        title: KukaDam
12        weight: 2
13        params:
14            sidebar:
15                subtitle: "晚来天欲雪<br>能饮一杯无"

Markdown样式

键盘样式

参考 Hugo Stack 魔改美化 | Naive Koala

在 /assets/scss/custom.scss 中加入以下代码：

 1// 键盘样式
 2kbd {
 3  margin: 0 .1em;
 4  padding: .1em .6em;
 5  font-size: .8em;
 6  color: #242729;
 7  background: #fff;
 8  border: 1px solid #adb3b9;
 9  border-radius: 3px;
10  box-shadow: 0px 1px 0 rgba(12, 13, 14, 0.2), 0 0 0 2px #fff inset;
11  white-space: nowrap;
12  vertical-align: middle;
13  font-family: monospace;
14}

这样就可以呈现如下 Markdown 中的键盘样式： <kbd>CTRL</kbd> + <kbd>C</kbd>

CTRL + C

图床链接图片居中

目前 Stack 默认只支持本地引用的图片居中，而在使用 url 图片链接时没有居中格式。在 /assets/scss/partials/layout/article.scss Line 256 处（同级任意位置）增加以下代码：

1// Center image from url source
2p > img {
3    display: block;
4    margin: 0 auto;
5    max-width: 100%;
6    height: auto;
7}

当启用fancybox时，上面的方法对fancybox不起作用，可以再上面代码的下方添加：

 1.post-img-view {
 2    text-align: center;
 3
 4    a {
 5        display: inline-block;
 6        text-decoration: none;
 7        border: none;
 8        box-shadow: none;
 9
10        img {
11            cursor: zoom-in;    // 鼠标显示放大镜图标
12            transition: transform 0.3s ease;    // 添加缩放动画效果
13
14            &:hover {
15                transform: scale(1.02);     // 悬停时轻微放大
16            }
17        }
18    }
19}

图片放大

修改stack主题的配置文件： hugo.yaml，在params中添加：

1params:
2  fancybox: true

在/layouts/_default/_markup/render-image.html合适位置补充：

1{{if .Page.Site.Params.fancybox }}
2<div class="post-img-view">
3<a data-fancybox="gallery" href="{{ .Destination | safeURL }}">
4<img src="{{ .Destination | safeURL }}" alt="{{ .Text }}" {{ with .Title}} title="{{ . }}"{{ end }} />
5</a>
6</div>
7{{ end }}

记得把原来的代码注释，否则会渲染两张图

 1<!-- <img src="{{ $Permalink }}"
 2	{{ with $Width }}width="{{ . }}"{{ end }}
 3	{{ with $Height }}height="{{ . }}"{{ end }}
 4	{{ with $Srcset }}srcset="{{ . }}"{{ end }}
 5	loading="lazy"
 6	{{ with $alt }}
 7		alt="{{ . }}"
 8	{{ end }}
 9	{{ if $galleryImage }}
10		class="gallery-image" 
11		data-flex-grow="{{ div (mul $image.Width 100) $image.Height }}"
12		data-flex-basis="{{ div (mul $image.Width 240) $image.Height }}px"
13	{{ end }}
14> -->

同理，在 layouts\partials\article\components\footer.html 中添加：

1{{if .Page.Site.Params.fancybox }}
2<script src="https://cdn.jsdelivr.net/npm/jquery@3.5.1/dist/jquery.min.js"></script>
3<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/fancyapps/fancybox@3.5.7/dist/jquery.fancybox.min.css" />
4<script src="https://cdn.jsdelivr.net/gh/fancyapps/fancybox@3.5.7/dist/jquery.fancybox.min.js"></script>
5{{ end }}

为了看到效果，可以在\assets\scss\partials\layout\article.scss中修改图片放大时的动画：

 1.article-content {
 2    ...
 3    // 为 Fancybox 图片添加样式
 4    .post-img-view {
 5        text-align: center;
 6        
 7        a {
 8            display: inline-block;
 9            text-decoration: none;
10            border: none;
11            box-shadow: none;
12            
13            img {
14                cursor: zoom-in;    // 鼠标显示放大镜图标
15                transition: transform 0.3s ease;    // 添加缩放动画效果
16                
17                &:hover {
18                    transform: scale(1.02);     // 悬停时轻微放大
19                }
20            }
21        }
22}

字体修改

去字体网站，比如【100font】，下载自己想要的字体文件 .ttf

把字体文件放到放入assets/font下（没有自己建）

将以下代码修改并复制到layouts/partials/footer/custom.html文件中

字体名：给字体命名一个别名，随便填写就好，保持统一就行
字体文件名：字体文件的全名，带后缀名的，也就是 xxx.ttf

 1<style>
 2  @font-face {
 3    /* 提高自定义字体加载速度 */
 4    unicode-range: U+4E00-9FFF,U+0025-00F0,U+3040-30FF,U+1100-11FF,U+3130-318F,U+AC00-D7FF;
 5    font-family: '字体名';
 6    src: url({{ (resources.Get "font/字体文件名").Permalink }}) format('truetype');
 7  }
 8
 9  :root {
10    --base-font-family: '字体名';
11    --code-font-family: '字体名';
12  }
13</style>

测试：l，L，i，I ~~（这几个字母字体用不好分不清）~~

固定代码块高度

把以下内容添加到 assets/scss/partials/article.scss ：

 1.article-content {  // 大概 line 205
 2   .highlight {  // line 331
 3      background-color: var(--pre-background-color);
 4      padding: var(--card-padding);
 5      position: relative;
 6      ...
 7      // 修改
 8      pre {  // 可以注释之前的
 9        margin: initial;
10        padding: 0;
11        margin: 0;
12        width: auto;
13        max-height: 30em;
14        scrollbar-width: none; /* Firefox */
15        &::-webkit-scrollbar {
16            display: auto;
17            /* Chrome Safari */
18        }
19      }
20  }
21}

固定高度后，还要去.yaml文件中修改参数，否则行号和代码块的滚动不一致

1markup:
2  highlight:
3  	lineNos: true
4    lineNumbersInTable: true
5    # lineNumbersInTable：使用表来格式化行号和代码, 而不是标签。这个属性一般设置为 true.
6    # lineNos：是否使用行号

设置lineNumbersInTable: false后，一般手动复制代码块和copy键复制都会把行号复制上，具体的修改看第一节

组件

顶部返回按钮

参考Stack 主题的自定义 | L1nSn0w’s Log

个人不是很喜欢返回键把左边菜单隐藏，给自己留个档。

加载进度条

在layouts/partials/footer/custom.html加入代码：

 1<!-- 加载进度条 -->
 2<script src="https://cdn.jsdelivr.net/gh/zhixuan2333/gh-blog@v0.1.0/js/nprogress.min.js" integrity="sha384-bHDlAEUFxsRI7JfULv3DTpL2IXbbgn4JHQJibgo5iiXSK6Iu8muwqHANhun74Cqg" crossorigin="anonymous"></script>
 3<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/zhixuan2333/gh-blog@v0.1.0/css/nprogress.css" integrity="sha384-KJyhr2syt5+4M9Pz5dipCvTrtvOmLk/olWVdfhAp858UCa64Ia5GFpTN7+G4BWpE" crossorigin="anonymous" />
 4<script>
 5    NProgress.start();
 6    document.addEventListener("readystatechange", () => {
 7        if (document.readyState === "interactive") NProgress.inc(0.8);
 8        if (document.readyState === "complete") NProgress.done();
 9    });
10</script>

但这个方法可能在引入pjax后会失效，需要查看pjax文档进行监听

樱花背景

下载地址【sakura.js】(CTRL + C 保存)，并放到assets/background文件夹下

在layouts/partials/footer/custom.html加入代码：

1<!-- 樱花背景 -->
2<script src={{ (resources.Get "background/sakura.js").Permalink }}></script>

文章最后修改时间

在hugo.yaml加入代码：

 1frontmatter:
 2  # 按优先级排序：
 3  # :git - 文件提交修改时间
 4  # lastmod - 文章里 lastmod 字段
 5  # :fileModTime - 文件修改时间
 6  # :default - 默认时间
 7  lastmod: [":git", "lastmod", ":fileModTime", ":default"]    
 8  
 9enableGitInfo: true
10gitRepo: "https://github.com/your_username/your_username.github.io"

这个方法比较简单，但是时间会出现在文章末尾：

更新时间的格式去 hugo.yaml 中的 params.dateFormat.lastUpdated 进行修改：

1dateFormat:
2    published: 2006-01-02
3    lastUpdated: 2006-01-02

留档：文章开头显示更新时间，参考【Hugo】Stack主题自定义修改

页面浏览量

这里用的是vercount

修改layouts/partials/footer/custom.html，引入脚本：

1<script defer src="https://cn.vercount.one/js"></script>

修改layouts/partials/article/components/footer.html，（没有文件夹可以从模板中复制）在合适的位置下加入代码：

 1<footer class="article-footer">
 2    {{ partial "article/components/tags" . }}
 3
 4    {{ if and (.Site.Params.article.license.enabled) (not (eq .Params.license false)) }}
 5    <section class="article-copyright">
 6		...
 7    </section>
 8    {{ end }}
 9
10    {{- if ne .Lastmod .Date -}}
11    <section class="article-lastmod">
12		...
13    </section>
14    {{- end -}}
15    <section>
16        页面浏览量<span id="vercount_value_page_pv">loading... </span>
17    </section>
18</footer>

若想浏览次数出现在文章开头，参考【Hugo】Stack主题自定义修改，但是会有bug，咱小白先弄简单的。

页面样式

首页文章标题悬停动画

F12 打开开发者模式，找到标题元素的位置，是在.article-list下的article/h2元素的a标签

在assets/scss/custom.scss文件中添加代码

1.article-list article h2 a {
2    display: inline-block;
3    transition: transform 0.25s ease;
4}
5
6.article-list article h2 a:hover{
7    transform: scale(1.05);
8}

首页文章分类悬停动画

同理找到该标签的位置，在article-category 的 a 标签中

添加assets/scss/custom.scss文件中添加代码:

1.article-category a {
2  display: inline-block;
3  transition: transform 0.25s ease;
4}
5
6.article-category a:hover {
7  transform: scale(1.05);
8}

右侧边栏动画

原理和上面首页的动画方式类似，找到相应位置，在assets/scss/custom.scss中添加代码就行

 1//右侧标签悬停动画
 2.tagCloud .tagCloud-tags a {
 3  display: inline-block;
 4  transition: transform 0.25s ease;
 5}
 6
 7.tagCloud .tagCloud-tags a:hover {
 8  transform: scale(1.05);
 9}
10
11//归档小图标放大动画
12.archives .widget-archive--list {
13  display: inline-block;
14  transition: transform 0.25s ease;
15}
16
17.archives .widget-archive--list:hover {
18  transform: scale(1.05);
19}

参考文献

小白hugo博客装修笔记（2）- B1ain’s Blog

Hugo-stackの美化 II

Hugo Stack 魔改美化 | Naive Koala

Stack 主题的自定义 | L1nSn0w’s Log

【Hugo】Stack主题自定义修改

凡凡小站