Hugo 内容写法备忘
目录
这篇只管正文怎么写。发文流程见：《Hugo + Congo 发文流程》；模板特调见：《Congo 站点定制记录》。
图片布局 #
普通图片 #
单张图片直接写标准 Markdown：
Markdown
1当前站点的普通正文图片会自动接入点击放大；但它们是单图查看，不会串成整篇文章图库。
手机截图对比 phone-shots #
Markdown
1{{< phone-shots caption="手机截图对比" >}}
2
3
4{{< /phone-shots >}}实际效果：
微博式九宫格 #
Markdown
1{{< phone-shots layout="weibo" caption="微博式图片网格" >}}
2
3
4
5{{< /phone-shots >}}常用参数 #
| 参数 | 默认值 | 用途 |
|---|---|---|
layout | compare | compare 为手机长截图对比；weibo 为方格九宫格 |
columns | compare 为 2，weibo 为 3 | 每行几张图 |
gap | compare 为 0.45rem，weibo 为 0.35rem | 图片间距 |
maxHeight | 42rem | compare 模式下单张截图最大高度 |
fillColumn | 空 | 补齐列高 |
caption | 空 | 整组说明文字 |
phone-shots 组图会自动接入图库浏览：上一张 / 下一张、键盘 ← →、手机横向滑动、Mac 触控板横向翻图都支持。
媒体分享 #
YouTube #
Markdown
1{{< youtube ZJthWmvUzzc >}}
2{{< youtube id="ZJthWmvUzzc" >}}X（原 Twitter） #
Markdown
1{{< x user="DesignReviewed" id="1085870671291310081" >}}TikTok #
Markdown
1{{< tiktok url="https://www.tiktok.com/@hinatazakanews/video/7619919230682565908" >}}Bilibili #
Markdown
1{{< bilibili id="BV1hx411T7XW" >}}
2{{< bilibili id="BV1Gg411m75M" p="19" auto="1" >}}
3{{< bilibili url="https://www.bilibili.com/video/BV1hx411T7XW?p=2" >}}音乐 #
| 平台 | 核心参数 | 说明 |
|---|---|---|
| Spotify | platform="spotify" + id | 支持 track / album / playlist |
| Apple Music | platform="apple" + src | 直接贴 Apple Music 页面链接 |
| 通用 iframe | src | 兜底方式 |
Markdown
1{{< music
2 platform="spotify"
3 id="2kM92TK9i4lnxE8IVLpgOm"
4 title="ジャーマンアリイス"
5 compact="true"
6 theme="light"
7>}}提示框 / 折叠 / 过期声明 #
GitHub 风格提示框 #
当前站点已经兼容 GitHub Markdown callout，正文里可以直接写：
Markdown
1> [!NOTE]
2> 补充说明、背景信息。
3
4> [!TIP]
5> 快速技巧或建议。
6
7> [!IMPORTANT]
8> 必须遵守的关键信息。
9
10> [!WARNING]
11> 可能遇到的问题与风险。
12
13> [!CAUTION]
14> 危险操作：执行前请确认后果。如果你想顺手写折叠态，也兼容 Obsidian 风格：
Markdown
1> [!WARNING]- 风险说明
2> 默认收起，点开查看。
3
4> [!TIP]+ 经验技巧
5> 默认展开。其中：
+= 默认展开-= 默认收起- GitHub 本身只认基础五类；
success/forbid/critical这类站内扩展，仍建议继续用短代码
callout #
如果你想显式控制类型、标题、折叠和打开状态，继续用站内 callout 短代码：
Markdown
1{{< callout type="note" >}}
2补充说明、背景信息。
3{{< /callout >}}
4
5{{< callout type="warning" fold="true" >}}
6长文案默认收起。
7{{< /callout >}}
8
9{{< callout type="caution" fold="true" open="true" >}}
10高危说明默认展开。
11{{< /callout >}}常用类型：
| type | 默认语义 |
|---|---|
note | 注意 |
tip | 提示 |
important | 重要 |
warning | 警告 |
caution | 小心 |
success | 站内扩展：完成 / 成功 |
forbid / danger / critical | 站内扩展：高风险别名 |
fold #
通用折叠块可以直接写：
Markdown
1{{< fold title="中性折叠" >}}
2术语解释、剧透、附录等。
3{{< /fold >}}
4
5{{< fold title="带类型的折叠" type="warning" >}}
6等价于 `callout type="warning" fold="true"`。
7{{< /fold >}}outdated #
过期提示用于给旧内容加时间阈值提醒：
Markdown
1{{< outdated from="2025-06-01" >}}
2{{< /outdated >}}
3
4{{< outdated from="2025-06-01" years="2" >}}
5{{< /outdated >}}| 参数 | 说明 |
|---|---|
from / 位置参数 | 基准日 |
years | 满几年才显示，默认 1 |
| 正文 | 省略则用默认动态句；有正文则完全自定义 |
怎么选 #
| 需求 | 用什么 |
|---|---|
| 普通提示 | GitHub 风格 > [!NOTE] 等 |
| 分色且可控 | callout |
| 折叠附录 / 剧透 | fold |
| 过期声明 | outdated |
诗词 / 注音 #
poem #
Markdown
1{{< poem title="蝶恋花·春景" author="苏轼〔宋代〕" dir="h" >}}
2花褪残红青杏小。
3huā tuì cán hóng qīng xìng xiǎo
4
5燕子飞时，绿水人家绕。
6yàn zi fēi shí lǜ shuǐ rén jiā rào
7{{< /poem >}}ruby #
Markdown
1我喜欢{{< ruby py="chūn jǐng" >}}春景{{< /ruby >}}胜过秋天。实际效果：我喜欢春景胜过秋天。
数学公式（KaTeX） #
先放一次加载短代码：
Markdown
1{{< katex >}}行内公式：
Tex
1质能关系：\(E = mc^2\)块级公式：
Tex
1$$
2\sum_{k=1}^{n} k = \frac{n(n+1)}{2}
3$$实际效果：
$$ \sum_{k=1}^{n} k = \frac{n(n+1)}{2} $$时序图（Mermaid） #
Markdown
1{{< mermaid >}}
2sequenceDiagram
3 autonumber
4 作者->>Hugo: hugo server -D
5 Hugo-->>浏览器: 本地预览
6{{< /mermaid >}}实际效果：
sequenceDiagram
autonumber
作者->>Hugo: hugo server -D
Hugo-->>浏览器: 本地预览
杂项 #
行内剧透 spoiler #
Markdown
1这是普通内容，{{< spoiler >}}这是剧透{{< /spoiler >}}。
2这是普通内容，{{< spoiler text="这是剧透" >}}。实际效果：这是普通内容，这是剧透。
键盘按键 kbd #
直接写原生 HTML 即可：
Markdown
1按 <kbd>Ctrl</kbd> + <kbd>C</kbd> 复制
2按 <kbd>⌘</kbd> + <kbd>K</kbd> 打开链接面板显示效果：按 Ctrl + C 复制。
正文标注 #
原生 HTML 仍然能混写，例如：
Markdown
1<span style="text-decoration: wavy underline; color: red;">波浪线</span>
2<u>下划线文字</u>
3<span style="text-emphasis: dot; text-emphasis-position: under;">文字下方着重点</span>