网站 on RunicDolphin806

APlayer

Sun, 17 Aug 2025 00:00:00 +0000

以下由Hugo的stack主题演示，其他的可作为参考。

引入APlayer

在Hugo工作文件夹的layouts/partials/footer文件夹中新建一个文件，命名为 aplayer.html。
在 aplayer.html中输入以下内容：

 1<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/aplayer/dist/APlayer.min.css">
 2<div id="aplayer"></div>
 3<script src="https://cdn.jsdelivr.net/npm/aplayer/dist/APlayer.min.js"></script>
 4
 5<script>
 6    const ap = new APlayer({
 7        container: document.getElementById('aplayer'),
 8        fixed: true,
 9        listFolded: true,
10        lrcType: 3,
11        audio: [{
12            name: 'example',
13            artist: 'example',
14            url: 'https://example.mp3',
15            lrc: 'example.lrc',
16            cover: 'example.png'
17        }]
18    });
19</script>

在layouts/partials/footer中新建一个文件夹，命名为custom.html，在其中输入：

1{{ partialCached "footer/aplayer.html" . }}

这样，aplayer就成功导入到网页中了。

修改APlayer样式

实现播放进度保存

 1<script>
 2    /**
 3    * 页面销毁前监听
 4    */
 5    window.onbeforeunload = () => {
 6        // 将播放信息用对象封装，并存入到localStorage中
 7        const playInfo = {
 8            index: ap.list.index,
 9            currentTime: ap.audio.currentTime,
10            paused: ap.paused
11        };
12        localStorage.setItem("playInfo", JSON.stringify(playInfo));
13    };
14
15    /**
16        * 页面加载后监听
17        */
18    window.onload = () => {
19        // 从localStorage取出播放信息
20        const playInfo = JSON.parse(localStorage.getItem("playInfo"));
21        if (!playInfo) {
22            return;
23        }
24        // 切换歌曲
25        ap.list.switch(playInfo.index);
26        // 等待500ms再执行下一步(切换歌曲需要点时间，不能立马调歌曲进度条)
27        setTimeout(() => {
28            // 调整时长
29            ap.seek(playInfo.currentTime);
30            // 是否播放
31            if (!playInfo.paused) {
32                ap.play()
33            }
34        }, 500);
35    };
36</script>

实现隐藏播放器图标

 1<style>
 2    .aplayer-fixed.aplayer-narrow .aplayer-body {
 3        left: -70px !important;
 4        /* 默认情况下缩进左侧70px，只留一点箭头部分 */
 5    }
 6
 7    .aplayer-fixed.aplayer-narrow .aplayer-body:hover {
 8        left: 0 !important;
 9        /* 鼠标悬停是左侧缩进归零，完全显示按钮 */
10    }
11</style>

导入pjax实现音乐不间断播放

pjax是一项页面切换不加载技术，可实现切换网页后音乐不间断。

导入pjax

在layouts/partials/footer中新建文件，命名为pjax.html.
在文件中写入代码：

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

这样pjax就成功导入网页中了。

修复网页样式

在pjax.html中加入以下内容：

 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                // 放行，交给pjax自己处理
12                pjax._handleResponse(responseText, request, href, options);
13            }
14        } else {
15            // handle non-HTML response here
16        }
17    }
18</script>

修复主题切换

在pjax.html中加入以下内容。

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

修复搜索

修改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}

tsx 类型的文件引入方式有点特殊，需要我们修改main.ts的引入方式，修改layouts/partials/footer/components/script.html，改法参考layouts/page/search.html，把JSXFactory，createElement补充上就好
修改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}

修复Latex

修改layouts/partials/article/components/math.html，添加一个元素标签，便于判断文档是否使用了KaTeX

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

在layouts/partials/footer/custom.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>

取消pjax的时间戳

pjax会默认给网页加上时间戳，具体为表现为?t=1724141234567的样式，这样会使页面间的跳转出现问题，建议关闭。

在pjax.html中引入：

1<script>
2    document.addEventListener('DOMContentLoaded', function () {
3        if (window.pjax) {
4            window.pjax.options.cacheBust = false; // 关闭时间戳参数
5        }
6    });
7</script>

Hugo-stack主题装饰

Sat, 02 Aug 2025 00:00:00 +0000

基本原理

Hugo的stack主题提供了自定义样式的接口，主要在layouts/partials/footer/custom.html和assets/scss/custom.scss中
Hugo的文件可以实现文件覆盖。只要文件位置与themes文件夹中的相同，就会先加载自定义文件。

页面布局

首页文章样式

在/assets/scss/custom.scss加入

 1/*主页文章图片样式*/
 2$image-scale: 1.2;
 3.article-list article .article-image img {
 4    width: 100%;
 5    height: 150px;
 6    object-fit: cover;
 7    //不同显示器（手机，小屏幕电脑，大屏幕电脑）显示的图片高度大小
 8    @include respond(sm) {
 9        height: 305px;
10    }
11    
12    @include respond(md) {
13        height: 305px;
14    }
15    @include respond(xl) {
16        height: 325px;
17    }
18}
19
20/*主页文章图片圆角*/
21.article-list article {
22    --card-border-radius: 24px;
23}
24
25/*文章标签圆角*/
26.article-category a, .article-tags a {
27    border-radius: 11px;
28}
29
30
31/*鼠标移动到文章图片放大*/
32.article-list article .article-image {
33    position: relative;
34    overflow: hidden; //不显示超出的部分
35}
36
37.article-list article .article-image img:hover {
38    transform: scale($image-scale); //放大尺寸
39}
40
41.article-list article .article-image img {
42    transition: transform 0.85s ease-in-out;//持续时间
43}

修改归档和友链界面

修改assets/scss/custom.scss文件，引入以下css样式代码：

 1@media (min-width: 1024px) {
 2    .article-list--compact {
 3        display: grid;
 4        // 目前是两列，如需三列，则后面再加一个1fr，以此类推
 5        grid-template-columns: 1fr 1fr;
 6        background: none;
 7        box-shadow: none;
 8        gap: 1rem;
 9
10        article {
11            background: var(--card-background);
12            border: none;
13            box-shadow: var(--shadow-l2);
14            margin-bottom: 8px;
15            margin-right: 8px;
16            border-radius: 16px;
17        }
18    }
19}

代码块样式

代码块行标设置

在config.yaml中找到highlight部分：

1highlight:
2    noClasses: false
3    codeFences: true
4    guessSyntax: true
5    lineNoStart: 1
6    lineNos: true                   # 是否显示行号
7    lineNumbersInTable: false       # 行号是否独立成列
8    tabWidth: 4

MacOS风格图标

准备一张macOS代码块的红绿灯图片放到static/icons文件夹下，或者将以下代码写入code-header.svg文件中：

1<svg xmlns="http://www.w3.org/2000/svg" version="1.1"  x="0px" y="0px" width="450px" height="130px">
2    <ellipse cx="65" cy="65" rx="50" ry="52" stroke="rgb(220,60,54)" stroke-width="2" fill="rgb(237,108,96)"/>
3    <ellipse cx="225" cy="65" rx="50" ry="52"  stroke="rgb(218,151,33)" stroke-width="2" fill="rgb(247,193,81)"/>
4    <ellipse cx="385" cy="65" rx="50" ry="52"  stroke="rgb(27,161,37)" stroke-width="2" fill="rgb(100,200,86)"/>
5</svg>

将以下代码复制进assets/scss/custom.scss文件中。

 1.highlight {
 2    border-radius: var(--card-border-radius);
 3    max-width: 100% !important;
 4    margin: 0 !important;
 5    box-shadow: var(--shadow-l1) !important;
 6}
 7
 8.highlight:before {
 9    content: "";
10    display: block;
11    // 这里填图片地址
12    background: url(../icons/macOS-code-header.svg) no-repeat 0;
13    background-size: contain;
14    height: 18px;
15    margin-top: -10px;
16    margin-bottom: 10px;
17}

复制不显示行号

在assets/ts/main.ts中找到copyButton项，修改为以下内容：

 1copyButton.addEventListener('click', () => {
 2    // 创建一个临时容器来克隆代码块的内容
 3    const tempCodeBlock = codeBlock.cloneNode(true) as HTMLElement;
 4
 5    // 删除行号，行号的元素是 <span class="ln">
 6    const lineNumbers = tempCodeBlock.querySelectorAll('.ln');
 7    lineNumbers.forEach(lineNumber => lineNumber.remove());
 8
 9    // 获取没有行号的纯文本内容
10    const codeText = tempCodeBlock.textContent;
11
12    navigator.clipboard.writeText(codeText || '')
13    // navigator.clipboard.writeText(codeBlock.textContent)
14        .then(() => {
15            copyButton.textContent = copiedText;
16
17            setTimeout(() => {
18                copyButton.textContent = copyText;
19            }, 1000);
20        })
21        .catch(err => {
22            alert(err)
23            console.log('Something went wrong', err);
24        });
25});

可视化加载条

下载【文件】，并将压缩包中的topbar.min.js移动至assets/js中。
在layouts/partials/footer/custom中加入以下代码：

 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        topbar.hide();
22    })
23</script>

网页组件

若想在网页中加入自定义内容，一种方法是在模版中写入.html源码；另一种方法是将代码封装成组件（widget），再以链接的方式引入模板中。

后者可以方便地实现代码复用，对原模版的改动也最小。实际上，每个组件本质上就是一个网页文件（.html），然后放入模版文件中即可实现在网页上加载。

以下提供了几个示例，供您参考。

首页欢迎栏

在/layouts/partial/widget/中新建文件welcome-bar.html，写入以下内容：

 1<!-- 首页欢迎字幅 -->
 2<div class="welcome">
 3    <p style="font-size: 2rem; text-align: center; font-weight: bold">
 4        <span class="shake">👋</span>
 5        <span class="jump-text1" > Welcome</span>
 6        <span class="jump-text2"> To </span>
 7        <span class="jump-text3" style="color:#e99312">Wei Qi</span>
 8        <span class="jump-text9" style="color:#e99312">Blog</span>
 9    </p>
10</div>
11<!-- 首页欢迎字幅 -->

在/assets/scss/custom.scss里加入：

 1//首页欢迎板块样式
 2.welcome {
 3    color: var(--card-text-color-main);
 4    background: var(--card-background);
 5    box-shadow: var(--shadow-l2);
 6    border-radius: 30px;
 7    display: inline-block;
 8}
 9
10// 👋emoji实现摆动效果
11.shake {
12    display: inline-block;
13    animation: shake 1s;
14    animation-duration: 1s;
15    animation-timing-function: ease;
16    animation-delay: 0s;
17    animation-iteration-count: 1;
18    animation-direction: normal;
19    animation-fill-mode: none;
20    animation-play-state: running;
21    animation-name: shake;
22    animation-timeline: auto;
23    animation-range-start: normal;
24    animation-range-end: normal;
25    animation-delay: 2s;
26    @keyframes shake {
27        0% {
28            transform: rotate(0);
29        }
30        25% {
31            transform: rotate(45deg) scale(1.2);
32        }
33        50% {
34            transform: rotate(0) scale(1.2);
35        }
36        75% {
37            transform: rotate(45deg) scale(1.2);
38        }
39        100% {
40            transform: rotate(0);
41        }
42    }
43}
44
45// 实现字符跳动动画
46.jump-text1 {
47    display: inline-block;
48    animation: jump 0.5s 1;
49}
50.jump-text2 {
51    display: inline-block;
52    animation: jump 0.5s 1;
53    animation-delay: 0.1s;
54}
55.jump-text3 {
56    display: inline-block;
57    animation: jump 0.5s 1;
58    animation-delay: 0.2s;
59}
60.jump-text9 {
61    display: inline-block;
62    animation: jump 0.5s 1;
63    animation-delay: 0.9s;
64}   
65
66@keyframes jump {
67    0% {
68        transform: translateY(0);
69    }
70    50% {
71        transform: translateY(-20px);
72    }
73    100% {
74        transform: translateY(0);
75    }
76}

实际上，这些css代码也可以直接写在welcome-bar.html的<style></style>标签中，在以下组件中同理。

随机文字卡片

随机效果

随机效果依赖javascript脚本：

 1// 获取并展示文字内容
 2function showQuotes() {
 3    // 随机文字
 4    index = Math.floor(Math.random() * quotes.length);
 5    const quote = quotes[index];
 6        
 7    // 获取文字和作者信息
 8    const textElement = document.querySelector(".quote-text");
 9    const authorElement = document.querySelector(".quote-author");
10
11    textElement.innerText = quote.quote;
12    authorElement.innerText = `—— ${quote.author}`;
13
14    // 渲染数学公式（可选）
15    renderMathInElement(textElement, {
16        delimiters: [
17            {left: '$$', right: '$$', display: true},
18            {left: '$', right: '$', display: false},
19            {left: '\\[', right: '\\]', display: true},
20            {left: '\\(', right: '\\)', display: false}
21        ]
22    });
23};

完善实现事件还需要增加一个按钮，实现点击就能随机显示文字。

1<button id="new-quote">Random</button>

然后赋予其点击事件：

1<script>
2    document.querySelector("#new-quote").addEventListener("click", showQuotes);
3</script>

设置配置文件

如果将文字内容写在.html文件内部，可配置性不佳，而且会使代码臃肿。因此，可以将随机文字的内容写入json文件并放入static/文件夹中。

为什么放入static文件夹？

static文件夹存放网页的静态内容，通俗点就是其中的内容就在站点目录之下。例如站点名为https://www.example.com，那么static/quotes.json就在https://www.example.com/quote.json处，在寻找时可以直接输入/quotes.json。

密码栏

在网页中显示组件

主页显示

在index.html中加入：

1<section class="article-list">
2    ...
3    {{ partial "widget/你的组件名.html" . }}
4    ...
5</section>

侧边栏

1page:
2    - type: toc
3    - type: 你的组件名

使用Hugo搭建网站

Sat, 02 Aug 2025 00:00:00 +0000

Hugo环境配置

点击进入Hugo下载地址，下载最新的release文件。

创建博客网站

准备步骤

在hugo对应的文件夹内打开cmd，输入hugo new site 你的文件夹名，可以看到多出一个新的空文件夹。

进入空文件夹，在cmd中输入hugo service build。可以看到网站在localhost:1313转发，在浏览器中输入该网址即可看到当前网站的内容。

下载Hugo主题

在Hugo官网上进入Theme，下载需要的主题文件，解压后放入网站文件夹的theme子文件夹。

接着在下载的主题文件夹中复制content文件夹和hugo.yaml（或hugo.toml）文件，粘贴到你的网站文件夹中。

打开主题的配置文件，找到theme: hugo-theme-stack一行，这里标明所使用主题的名称，须保持名称与主题文件夹的名称相同，否则要修改其一。再次执行hugo service build，即可看到使用了主题的网站。

创建自定义内容

Hugo网站的文章内容均在content文件夹中，每篇文章对应一个子文件夹。

每篇文章均采用Markdown语法书写，通常在文章开头有类似的配置文字：

1---
2title: xxxxx            # 文章的标题
3description: xxxxx      # 文章的副标题
4date: xxxxx             # 文章的日期
5slug: xxxxx             # 文章在静态页面所属的文件夹
6categories:
7    - xxxxx             # 文章所属类别
8---

必须包含这些内容网站才会显示对应文章。

文章正文参照Markdown语法规则。

Hugo构建命令

完成网页的编辑后，需执行Hugo的构建命令，方能生成网页文件。

1hugo server -D    #构建本地网页
2hugo              #构建在线网页
3hugo --cleanDestinationDir  #清理构建文件夹

注意事项

使用hugo server -D命令构建的是本地网页，遇到超链接时会重定向到localhost:1313/xxx，不能直接部署到GitHub等服务器上，必须再执行一次hugo命令清除本地链接的内容之后，才能正确部署。

参考视频：

在Github上托管网页

Github网站提供了“Github Pages”功能，允许用户为自己的项目部署一个静态网页。

创建网站仓库

注册Github账号，并创建一个新仓库，命名为你的用户名.github.io。

为什么命名为你的用户名.github.io？

Github的Pages分为两种，一种为用户Pages，另一种为项目Pages。用户Pages每个账号只能拥有一个，域名为https://你的用户名.github.io；项目Pages数目不限，域名为https://你的用户名.github.io/你的项目名.

因此，设置仓库名为你的用户名.github.io可以使网站地址更简洁。

生成静态网页文件

在命令行中执行

1hugo

执行完成后会在工作区文件夹中出现一个public文件夹，进入该文件夹。

上传文件至Github

参见：玩转Github

参考视频：

插入其他资源

插入图片

1{{< figure src="图片路径" width="宽度" height="高度" title="图片标题" >}}

插入视频

1<!-- 插入Bilibili视频 -->
2{{/* < bilibili bv号 分p(可选) */>}}

Hugo网站搭建内部链接

使用相对路径链接

相对路径是根据当前页面的位置来定位目标页面的路径。这是最简单且常用的方式之一。

假设你的网站目录结构如下：

1content/
2├── about.md
3├── blog/
4│   ├── post1.md
5│   └── post2.md
6└── projects.md

在about.md中链接到 blog/post1.md：

1[访问博客文章](blog/post1)

在 blog/post1.md 中链接到projects.md：

1[查看项目](../projects)

在 blog/post1.md 中链接到同级的post2.md：

1[查看另一篇文章](post2)

使用绝对路径链接

绝对路径是从网站的根目录开始的完整路径。这种方式的好处是不受当前页面位置的影响。

假设你的网站根目录是 https://example.com ，目录结构同上。

在about.md中链接到 blog/post1.md：

1[访问博客文章](/blog/post1)

在 blog/post1.md 中链接到projects.md：

1[查看项目](/projects)

使用 Hugo 的 ref 和 relref 短代码

Hugo 提供了 ref 和 relref 短代码，可以更智能地处理内部链接。这些短代码会根据页面的路径自动解析链接。

ref 短代码：生成绝对路径链接。

1[访问博客文章]({{< ref "blog/post1.md" >}})

relref 短代码：生成相对路径链接。

1[访问博客文章]({{< relref "blog/post1.md" >}})

链接到页面的特定部分

如果你希望链接到页面的某个特定部分（例如某个标题），可以通过锚点（anchor）来实现。

假设post1.md中有一个标题：

1## 我的博客文章内容 {#my-section}

你可以通过以下方式链接到这个部分：

1[查看博客文章的特定部分](/blog/post1#my-section)

链接到页面的别名

如果某些页面有别名（例如在 frontmatter 中定义了 aliases），你可以直接使用别名来链接。

假设post1.md的 frontmatter 中定义了别名：

1---
2title: "我的博客文章"
3aliases:
4  - "/old-post1"
5---

你可以通过以下方式链接到它：

1[访问旧的博客文章](/old-post1)