博客精装修

本文最后更新于 49 天前（2025-12-10），部分内容可能已经过时。

新logo

叫 gpt 给我画了个 logo，元素就是姓名首字母啦，还是蛮喜欢的

本次博客换了个主题和评论系统，参考文章放在末尾了。算是找到比较靠谱的几篇文章。由于我使用较新的版本，所以并不是能很好的复现文章中的效果，不过也足够满意了

装修点

原先使用hugo-theme-stack 主题是由于接触 hugo 的教程中使用的就是这个，为了避免不必要的麻烦，初次基本都是按部就班复刻教程为主，这次心血来潮还是想换一个，挑了挑就觉得 papermod 不错，简单不复杂，不是很爱花哨的，但是也不想博客太丑了点

评论区

原先为了自部署，用了 waline，结果发现 papermod 没有直接支持。由于我前端功力不够，又不会 go，在 gpt-5 的帮助下也没成功用上，只能放弃用个简单的，挑了挑还是选择Giscus Hugo博客系统添加Giscus评论功能 - Whohhの博客参考这篇文章倒是一点困难没有就完成了，只是还是想要有自己部署的心里才舒服，不明白这是什么心态，精力有限，现在博客是无人问津的状态，也不需要操心这件事情

便于阅读

Mermaid图

这个还是特别有用的，尤其是在 LLM 的帮助下，不少文章中画一个 markdown 中能渲染的流程图框架图之类的变得异常轻松

以下摘用自台运鹏大佬的文章

Mermaid js 可以可以让我们用代码的方式画流程图（如上图），在文章的概念比较多或者关系复杂时，流程图就可以让读者更容易看懂，故而也引入了 mermaid 的实现

首先创建 layouts/_default/_markup/render-codeblock-mermaid.html，写入以下内容：

1
2
3
4
5
<!-- 因为正常写会有 ```meraid ... ``` -->
<pre class="mermaid">
   {{- .Inner | htmlEscape | safeHTML }}
</pre>
{{ .Page.Store.Set "hasMermaid" true }}

这样就可以将 mermaid 这种特殊的 codeblock 加入渲染机制里，同时设置 hasMermaid 为 true，方便后面判断是否加载 mermaid js。接着我们创建 layouts/partials/mermaid.html，来让 mermaid js 对我们写的代码进行渲染

同时支持亮暗自动切换，大部分代码片段取自于 mermaid-js 社区的讨论，然而默认的代码是初次渲染是查看 localStorage 是否包含 pref-theme，很多时候用户并未手动点击切换是不会有这个值，即为 null。我这里是判断 document.body.className 是否包含 dark 来判断，更为准确

mermaid 的字体设置依然是对齐正文，使用 mermaid.init() 设置即可：

显示已折叠代码（66 行）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
{{ if .Page.Store.Get "hasMermaid" }}
<script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script>
<script>
  const elementCode = ".mermaid";
  const loadMermaid = function (theme) {
    mermaid.initialize({ theme });
    mermaid.init({
      theme,
      themeVariables: { // 这里设置字体跟正文一致
        fontFamily: ["SFProText-Regular", "LXGWWenKaiScreenR"]
      }}, document.querySelectorAll(elementCode));
  };
  const saveOriginalData = function () {
    return new Promise((resolve, reject) => {
      try {
        var els = document.querySelectorAll(elementCode),
          count = els.length;
        els.forEach((element) => {
          element.setAttribute("data-original-code", element.innerHTML);
          count--;
          if (count == 0) {
            resolve();
          }
        });
      } catch (error) {
        reject(error);
      }
    });
  };
  const resetProcessed = function () {
    return new Promise((resolve, reject) => {
      try {
        var els = document.querySelectorAll(elementCode),
          count = els.length;
        els.forEach((element) => {
          if (element.getAttribute("data-original-code") != null) {
            element.removeAttribute("data-processed");
            element.innerHTML = element.getAttribute("data-original-code");
          }
          count--;
          if (count == 0) {
            resolve();
          }
        });
      } catch (error) {
        reject(error);
      }
    });
  };

  saveOriginalData().catch(console.error);
  // 不要用 localStorage.getItem("pref-theme")，因为有些时候会为 null
  let isdark = document.body.className.includes("dark");
  if (isdark) {
    resetProcessed().then(loadMermaid("dark")).catch(console.error);
  } else {
    resetProcessed().then(loadMermaid("neutral")).catch(console.error);
  }
  document.getElementById("theme-toggle").addEventListener("click", () => {
    resetProcessed();
    document.body.className.includes("dark")
      ? loadMermaid("neutral")
      : loadMermaid("dark").catch(console.error);
  });
</script>
{{ end }}

最后再在 layouts/_default/single.html 中加入引用 mermaid.html 的部分，注意，single.html 你如果一开始没有，需要先去主题 themes/PaperMod/layouts/_default/single.html 那里拷贝原来的 single.html 到上面这个地址

1
2
3
4
<article>
  <!-- 省略上面的 -->
  {{- partial "mermaid.html" . }}
</article>

代码折叠

博主原实现

在 layouts/shortcodes/collapse.html 中加入以下内容：

1
2
3
4
5
6
7
8
{{ if .Get "summary" }}
{{ else }}
{{ warnf "missing value for param 'summary': %s" .Position }}
{{ end }}
<p><details {{ if (eq (.Get "openByDefault") true) }} open=true {{ end }}>
  <summary markdown="span">{{ .Get "summary" | markdownify }}</summary>
  {{ .Inner | markdownify }}
</details></p>

这个我看了一下源码，需要手动在要折叠的块上写\{\{< collapse >\}\}\{\{< /collapse >\}\} 我加了反斜杠因为我的 papermod 里有这个 short code，不记得是我加错地方了还是什么情况

不行，感觉太不优雅，所以我的方法是下面的

打开/新建layouts/_markup/render-codeblock.html：不是 layouts/_default/_markup hugo 文档，Code block render hooks

写入以下内容

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{{/* 计算行数 */}}
{{ $lines := (len (split .Inner "\n")) }}
{{ $autoThreshold := 15 }} {{/* 超过多少行自动折叠，自行调整 */}}
{{ $needCollapse := ge $lines $autoThreshold }}
{{ if $needCollapse }}
<details>
<summary>显示已折叠代码（{{ $lines }} 行）</summary>
{{ end }}
{{ $r := transform.HighlightCodeBlock . }}
{{ $r.Wrapped }}
{{ if $needCollapse }}
</details>
{{ end }}

这样子超过多少行就会折叠了，也懒得我去设置

盘古之白

由于很早换成了微信输入法，中英文或中数字之间会自动空格，美观不少，这次在这里了解到这个空格也被称为「盘古之白」，像是劈开了这几者之间的混沌，很有意思，但是没有装修进来

侧面目录

这个博主的在我这一直不生效最终是把 assets/css/extended/toc.css写入以下内容生效的，虽然似乎丑了点。但是现在能用就行

[css] 显示已折叠代码（202 行）

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
  

:root {

--article-width: 720px;

--toc-width: 230px; /* adjust as needed */

--toc-gap: 4.5rem; /* safe gap between TOC and article */

}

  

/* Base TOC box appearance */

.toc {

margin: 0 2px 40px 2px;

border: 1px solid var(--border);

background: var(--entry);

border-radius: var(--radius);

padding: 0.4em;

}

  

/* Fully detached left sidebar TOC on desktop */

@media (min-width: 1100px) {

.toc {

position: fixed; /* fully detach from article flow */

top: 6.5rem; /* below header; tweak to your navbar height */

left: max(16px, calc(50% - (var(--article-width) / 2) - var(--toc-width) - var(--toc-gap)));

transform: translateX(-4px);

width: var(--toc-width);

max-height: calc(100vh - 8rem); /* keep a bit of breathing room */

overflow: auto;

z-index: 3;

margin: 0; /* no flow margins when fixed */

box-shadow: 0 4px 14px rgba(0,0,0,.18);

backdrop-filter: saturate(140%) blur(6px);

}

  

.toc .inner a { text-decoration: none; opacity: .9; transition: opacity .15s ease, color .15s ease; }

.toc .inner a:hover { opacity: 1; color: var(--secondary); }

.toc ul { list-style: none; padding-left: .2rem; }

.toc li { position: relative; padding-left: .75rem; }

.toc li::before { content: ""; position: absolute; left: 0; top: .65em; width: .35rem; height: .35rem; border-radius: 50%; background: var(--tertiary); opacity: .6; }

}

  

.toc details summary {

cursor: zoom-in;

margin-inline-start: 20px;

padding: 12px 0;

}

  

.toc details[open] summary {

font-weight: 500;

}

  

.toc .inner {

margin: 0 0 0 20px;

padding: 0 15px 15px 20px;

font-size: 16px;

max-height: 83vh;

overflow-y: auto;

}

  

.toc .inner::-webkit-scrollbar-thumb {

background: var(--border);

border: 7px solid var(--theme);

border-radius: var(--radius);

}

  

.toc ul {

list-style-type: circle;

}

  

.toc li ul {

margin-inline-start: calc(var(--gap) * 0.5);

list-style-type: none;

}

  

.toc li {

list-style: none;

font-size: 0.95rem;

padding-bottom: 5px;

}

  

.toc .active {

font-size: 110%;

font-weight: 600;

color: #614a85;

text-decoration: underline;

}

  

.toc li a:hover {

color: var(--secondary);

}

  
  

/* Optional: ensure a tiny buffer between page edge and left TOC */

@media (min-width: 1400px) {

.page,

.main { padding-left: max(var(--gap), 0px); }

}

  

@media (max-width: 1099px) {

.toc { position: relative; left: auto; top: auto; max-height: none; box-shadow: none; backdrop-filter: none; }

}

@media (min-width: 1100px) and (max-width: 1360px) {

.toc { left: max(12px, calc(50% - (var(--article-width) / 2) - var(--toc-width) - (var(--toc-gap) + 5rem))); }

}

参考文章

感谢前辈大佬的文章。

台运鹏. (Dec. 17, 2024). 《Hugo PaperMod 主题精装修》[Blog post]. Retrieved from http://yunpengtai.top/posts/hugo-journey/

新logo#

装修点#

评论区#

便于阅读#

Mermaid图#

代码折叠#

盘古之白#

侧面目录#

参考文章#