主题 reimu 的短代码整理

WARNING

Info

本文使用 DeepSeek V4.1 Flash 辅助排版和资料收集

前言

每次写文章，想塞个链接卡片或者折叠面板，都得先去翻一遍主题仓库的 README.md，然后翻 Release Note ，翻不到还得再翻 layouts/shortcodes/ 里的模板文件
翻多了实在是烦，索性整理成一篇文章，以后再要用到就可以来看这个不用到处翻了

好像也可以让 Agent 直接看这个

另外主题的模板只用了一部分 Hugo 的能力，Hugo 自己还带了一批内置短代码，一起收进来了

正文

一些前置提醒

• Hugo 版本目前以0.158.0为准，之后会跟随主题升级而升级
• 主题是 hugo-theme-reimu，本站对样式进行了少许修改但是短代码是一样的
• 主题样式目前以 v0.16.0 为准，之后会跟随主题升级而升级
• 短代码的参数不能位置参数和命名参数混着用，要么全用位置参数，要么全用 key=value
• 参数值里带空格要用引号包起来，比如 title="Hello World"

一、主题自带的短代码

link 链接卡片

v0.14.0 引入，内外链通用卡片
用于替代 postLinkCard 和 externalLinkCard 这两个旧写法

示例

主题 reimu 的短代码整理

把 hugo-theme-reimu 主题自带的 shortcode 和 Hugo 内置 shortcode 速查表整理

用法

1
2

{{< link title="外链" link="https://www.baidu.com" cover="auto" escape="true" >}}
{{< link title="内链" path="post/guide/write-helper/reimu-shortcodes.md" cover="auto" escape="false" >}}

站内链接的目标找不到时，Hugo 构建会直接报错

friendsLink 友链卡片

初始版本 v0.0.1 引入，友链渲染卡片
读取 data/friends.yml，把里面所有友链渲染成一片卡片，无参数

示例

参见 友情链接

用法

1

{{< friendsLink >}}

除了友链基本用不到

postLinkCard / externalLinkCard 站内、站外卡片

初始版本 v0.0.1 引入，分别用于站内文章和站外链接的卡片
v0.14.0 版本后被 链接卡片 取代。

示例

主题 reimu 的短代码整理

把 hugo-theme-reimu 主题自带的 shortcode 和 Hugo 内置 shortcode 速查表整理

用法

1
2

{{< externalLinkCard title="外链" link="https://www.baidu.com" cover="auto" >}}
{{< postLinkCard path="post/guide/write-helper/reimu-shortcodes.md" cover="auto" >}}

这两个短代码的模板只读上面列出来的参数，多写的参数不会报错，但也不会有任何效果

这里写一下做留档，新写的话一律用 链接卡片 就好

alertBlockquote 提示块

v0.12.1 引入
给 Hugo v0.132.0 以下兜底，那些版本用不了块引用 render hooks，只能靠这个短代码显示带图标的提示框

示例

Tip

这里写内容，里面可以正常写 Markdown，比如 加粗、行内代码，也可以放列表：

• 第一项
• 第二项

用法

1
2
3

{{< alertBlockquote type="tip" >}}
这里写内容，里面可以正常写 Markdown
{{< /alertBlockquote >}}

type 可选的值和主题 CSS 里定义的配色：

Hugo v0.132.0 以上的 Hugo 版本可以直接用块引用提示框（> [!TIP] 那种写法），更推荐 Markdown 原生写法

details 折叠面板

v0.14.1 引入，只有 summary 一个参数，不填的话标题就是空的

示例

用法

1
2
3

{{< details summary="标题（点击展开）" >}}
折叠起来的内容，同样支持 Markdown
{{< /details >}}

注意这个短代码覆盖了 Hugo 内置的同名短代码，该主题的 details 没有 open、class 这些参数

tabs 标签页

v0.14.0 引入，借鉴 next、volantis、stellar 几个主题，用来做多方案并列展示

示例

用法

1
2
3
4
5
6

{{< tabs 1 "center" >}}
<!-- tab 方案一 -->
Windows 下的做法
<!-- tab 方案二@e60c -->
Linux 下的做法
{{< /tabs >}}

两个位置参数都可选：

每个标签页用 <!-- tab 标题 --> 分隔，tab 是固定前缀，后面才是自己的标题，中间有没有空格都行

标题里可以用 @ 加十六进制码点来加图标，码点来自主题配置里的 iconfont 项目：

• <!-- tab 标题 --> —— 只有文字
• <!-- tab @e60c --> —— 只有图标
• <!-- tab 标题@e60c --> —— 图标加文字

gallery 照片墙

v0.14.0 引入，把一组图片排成响应式照片墙，自动按图片宽高比分配空间
点开走 Photoswipe 灯箱，排列逻辑是每行高度固定 200px、最多放 4 张

示例

用法

1
2
3
4
5

{{< gallery >}}
![alt 文字](https://example.com/1.webp)
![alt 文字](https://example.com/2.webp)
![alt 文字](https://example.com/3.webp)
{{< /gallery >}}

无参数，往里面丢标准 Markdown 图片就行

grid 网格布局

v0.14.1 引入，内容分格展示，每格独立渲染 Markdown

示例

用法

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

{{< grid width=300 col=3 >}}
<!-- cell -->
第一格

这里有独立渲染的 Markdown
<!-- cell -->
第二格

- 列表项
- 列表项
<!-- cell -->
第三格

`行内代码`
{{< /grid >}}

格子之间用 <!-- cell --> 分隔，中间的空格加不加都能识别

上面示例里 >}} 前面留的那个空格不能省。col=3 这种不带引号的数值如果直接贴着 >}} 写，Hugo 会把 >}} 一起当成参数值，
然后报 unrecognized character in shortcode action。要么加空格，要么把值写成 col="3"

tagRoulette 标签轮盘

v0.12.0 引入，点击按钮从标签池里随机抽一个展示，卡片样式来自 5ime 的博客

示例

用法

1

{{< tagRoulette tags="记忆衰退,表达欲丧失,更加怠惰,无感,好想睡觉" icon="🕹️" >}}

页面加载时会自动滚一次，点击按钮再滚一次

heatMapCard 文章热力图

v0.8.0 引入，把全站文章按日期和字数铺成一张热力图，点格子弹出当天的文章列表

示例

用法

1

{{< heatMapCard levelStandard="1000,5000,10000" >}}

levelStandard 是等级阈值，按文章字数分级，默认 "1000,5000,10000"，也就是四档：≤1000 一档，≤5000 二档，≤10000 三档，再多就是最高档

渲染时会遍历全站所有文章算字数，文章多了这页会变慢，放一页就够了

二、Hugo 内置短代码

Hugo 自带的短代码，不需要在主题里定义就能用。

需要注意，主题里同名的短代码会覆盖 Hugo 内置的，reimu 的 details 就是这种情况。

figure 图片加图注

比裸 Markdown 图片多一层 figure + figcaption 结构，适合需要图注、署名、点击跳转的图

示例

用法

1

{{< figure src="图片地址" alt="替代文字" caption="图注文字" title="图注小标题" attr="作者" attrlink="https://example.com" >}}

其实用 ![说明](url "说明") 加一行 <center>图注</center>更实用一点

highlight 手动高亮代码

普通代码块用三个反引号就够了，highlight 用在需要单独指定高亮行的场合

示例

10
11
12
13
14

package main

func main() {
    println("hello")
}

用法

1
2
3
4
5
6
7

{{< highlight go "linenos=table,hl_lines=2-4 7,lineNoStart=10" >}}
package main

func main() {
    println("hello")
}
{{< /highlight >}}

位置参数依次是 CODE、LANG、OPTIONS。常用选项：

ref 和 relref 站内链接

给站内页面生成链接，ref 出绝对地址，relref 出相对地址

示例

https://blog.luochu.cc/post/guide/write-helper/%E4%B8%BB%E9%A2%98-reimu-%E7%9A%84%E7%9F%AD%E4%BB%A3%E7%A0%81%E6%95%B4%E7%90%86/ —— ref，绝对地址
/post/guide/write-helper/%E4%B8%BB%E9%A2%98-reimu-%E7%9A%84%E7%9F%AD%E4%BB%A3%E7%A0%81%E6%95%B4%E7%90%86/ —— relref，相对地址

用法

1
2

[文章标题]({{% ref "post/guide/write-helper/reimu-shortcodes.md" %}})
[文章标题]({{% ref path="post/guide/write-helper/reimu-shortcodes.md" lang="zh-cn" %}})

写的时候要用百分号定界（% 而不是 <、>），因为要的是链接地址本身，不是 HTML 块。

Hugo 自己的文档现在把 Markdown 里的 ref 标成了 obsolete，推荐直接用 Markdown 相对路径
找不到目标页面时默认直接报错终止构建，可以在配置里放宽：

1
2

refLinksErrorLevel: warning
refLinksNotFoundURL: /some/other/url

这个直接用 link 其实更方便（

param 读参数

把页面的 front matter 或者站点参数读进正文里

示例

本页标题是「主题 reimu 的短代码整理」，站点作者是「洛初」

用法

1

本页标题是 {{% param "title" %}}，站点作者是「{{% param "author" %}}

参数就是参数名，嵌套的用点号连起来，比如 author.name
页面 front matter 里没有就去找站点参数，两边都没有会直接报错，同样要用百分号定界

qr 二维码

Hugo v0.141.0 新增，把一段文字或网址渲染成二维码图片

示例

用法

1

{{< qr text="https://blog.luochu.cc/" level="medium" scale=4 >}}

youtube / vimeo / x / instagram

都是 oEmbed 嵌入，构建时需要能联网，断网的话会打警告，页面里留一段报错文本

示例

我不怎么用就不放示例了

用法

1
2
3
4

{{< youtube id="dQw4w9WgXcQ" autoplay="false" loading="lazy" >}}
{{< vimeo id="19899678" allowFullScreen="false" loading="lazy" >}}
{{< x user="SanDiegoZoo" id="1453110110599868418" >}}
{{< instagram CxOWiQNP2MO >}}

youtube 的参数比较多：

vimeo 是 id、allowFullScreen、loading、title、class，
其中 allowFullScreen 和 loading 是 v0.146.0 才加的

x 就两个参数，user 是账号名、id 是推文数字 ID，Hugo v0.141.0 新增，旧名叫 twitter

instagram 只接一个位置参数，从帖子链接里 /p/ 后面那段拿

已经被移除的

这几个写上去会直接让构建报错：

这篇就当自己的速查表用，后面主题或者 Hugo 升级有新东西再回来补
要是网站里有什么错误欢迎多多指正~