为啥要使用旁注 #
在文章写作中，有时需要为当前内容添加一些相关的小注释。如果使用传统的脚注，读者查看注释时通常需要跳到文章底部，这会打断阅读节奏，影响整体的 阅读流畅感 。
在 Hugo 中的实现
#
在参考了 sidenotes-in-hugo-with-fixit 和 sidenotes-using-ox-hugo 这两篇文章之后，我打算使用 Hugo 中 ShortCode 的功能来实现旁注功能。
定义 ShortCode 模版
#
在 layouts/shortcodes/sidenote.html 中定义
<span class="sidenote-number"><small class="sidenote">{{ .Inner }}</small></span>
使用 CSS 实现旁注效果
#
主要代码来源于上面提到的 这两篇博客，但是它们使用的 Hugo 主题和我所使用
我主要使用 Blowfish
的不一样，于是做了一些样式上的修改。
以下代码定义在 blog/assets/css/custom.css, 需要将这个文件添加到 hugo.toml 中，来保证 CSS 的生效。
[params.assets]
customCSS = ["css/custom.css"]
旁注的主要 CSS 实现
#
适配
当切换到白天模式的时候颜色会有问题，而且在手机上面看的时候旁注和正文挤在一起了 😵
了 Blowfish 的默认蓝色主题，添加了一些阴影和边框。
.sidenote {
font-size: 75%;
position: relative;
word-wrap: break-word;
overflow-wrap: break-word;
white-space: normal;
line-height: 1.3;
background: linear-gradient(90deg, #f7f9fa 0%, #ffffff 100%);
border-left: 4px solid var(--color-primary, #007acc);
padding: 0.6rem 0.9rem;
border-radius: 0.5rem;
color: #333;
transition: background-color 0.3s ease, border-color 0.3s ease;
}
/* Dark mode support */
@media (prefers-color-scheme: dark) {
.sidenote {
background: rgba(255, 255, 255, 0.05);
border-left-color: rgba(255, 255, 255, 0.2);
color: #ddd;
}
}
/* Wide viewport */
@media (min-width: 1400px) {
.sidenote {
float: left;
clear: left;
margin-left: -7rem; /* 从 -23vw 改成固定宽度单位，更适配 Blowfish */
/* text-align: right; */
width: 6rem; /* 内容更窄 */
line-height: 1.3;
top: -2.5rem;
margin-top: 0.5rem;
}
}
/* Narrow viewport */
@media (max-width: 1400px) {
.sidenote {
float: none;
text-align: left;
width: 100%;
margin: 1rem 0;
padding-left: 10%;
}
}
旁注自动计数 #
自动添加数字标注，并且添加了鼠标移动上去高亮旁注的效果。
/* Sidenote counter */
body {
counter-reset: sidenote-counter;
}
.sidenote-number {
counter-increment: sidenote-counter;
}
/* Counter before the sidenote in the margin. */
.sidenote::before {
content: "[ "counter(sidenote-counter)" ]";
position: relative;
vertical-align: baseline;
font-size: 0.9em;
font-weight: bold;
}
/* Counter in the main body. */
.sidenote-number::after {
content: counter(sidenote-counter);
display: inline-block;
vertical-align: super;
font-size: 0.65em;
font-weight: bold;
padding: 0.1em 0.3em;
text-align: center;
border-radius: 0.2rem;
/* background-color: #ff6f61; */
color: white;
}
.sidenote-number:hover::after {
background-color: var(--color-primary, #007acc);
color: white;
transform: scale(1.2);
transition: all 0.2s ease;
}
@media (min-width: 1400px) {
/* Highlight the sidenote when mouse hovers on the sidenote number in body. */
.sidenote-number:hover .sidenote {
border-left-color: var(--color-primary, #007acc);
box-shadow: 0 0 5px rgba(0, 122, 204, 0.2);
transition: all 0.3s ease;
}
}
目前的问题 #
移动端 #
字体全挤在正文中间，不好看。 百般武艺，此乃 Emacs （一）：用 Emacs 写博客 这篇文章中旁注的处理方法很好，在空间不够的时候，变成类似抽屉，可以弹出和收纳，不影响正文。
主题带来的问题 #
由于 Blowfish 这个主题，左边留的空白其实不是很大，导致只能将旁注的宽度压缩，而且目前使用的是固定大小的宽度，在比较大的屏幕上面，反而又会比较小。
在 Emacs 中的实现
#
Org 和 ox-hugo 的配置
#
定义 Org 代码块
#
为了方便生成 Hugo 的短代码，定义了一个 Org 代码块 sidenote 。
(add-to-list 'org-structure-template-alist '("n" . "sidenote"))
适配 ox-hugo 导出效果
#
在导出为 Markdown 时，去除 sidenote 代码块前后的空格，以确保旁注能正确地与前文文本连在一起并显示角标。
(add-to-list 'org-hugo-special-block-type-properties
'("sidenote" . (:trim-pre t :trim-post t)))
笔记中的配置 #
笔记开头添加，定义 Hugo 中的短代码
#+hugo_paired_shortcodes: %sidenote
这样就可以保证将 Org 如 1 中的写法转化如 2 中 Markdown 中的写法。
你好呀
#+begin_sidenote
这是旁注
#+end_sidenote
, 上面有一个旁注
你好呀
<span class="sidenote-number"><small class="sidenote">
这是旁注
</small></span>
, 上面有一个旁注