Shortcodes 与组件

提示框、折叠、标签页、文件树、链接卡片、原始 HTML、版本标记和时间线。

本篇属于 Markdown 语法手册。按章内目录跳转，代码块提供可复制源码，其后的正文和组件展示实际效果。

先学会安全展示源码

在 Markdown 文件的代码围栏内，把短代码起止符写成 {{</* 与 */>}}；百分号形式对应 {{%/* 与 */%}}。Hugo 输出时会去掉这对注释标记，让读者复制到可执行的语法。

下面的示例在本页源文件中已经转义，页面上的复制按钮复制到的是正常短代码。不要只用反斜杠转义花括号。

提示框 admonition

1
2
3

{{< admonition type="tip" title="写作提示" open=true >}}
先完成 **内容**，再微调样式。
{{< /admonition >}}

1
2
3

{{< admonition type="warning" title="发布前检查" open=false >}}
确认草稿状态、图片路径和合集链接。
{{< /admonition >}}

短代码与 Markdown 怎么配合

短代码解决 Markdown 本身不擅长的布局问题，但不应代替普通段落。一个提示只有一句话时，先考虑强调或引用；需要明确的“提醒”“警告”语义时，再使用提示框。

不能仅凭外观决定是否使用百分号：不同短代码内部实现不同。比如 admonition 和 details 已经主动调用页面 Markdown 渲染，而 tab 需要按本手册的嵌套写法处理正文。

一组不同语义的提示

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{{< admonition type="note" title="适用范围" >}}
本文只讨论当前固定版本的写法。
{{< /admonition >}}

{{< admonition type="success" title="检查完成" >}}
文章、图片和合集链接都已检查。
{{< /admonition >}}

{{< admonition type="danger" title="注意覆盖范围" >}}
不要将生成的 `public/` 目录当作内容源文件编辑。
{{< /admonition >}}

颜色服务于语义，不必为了配合站点主色把所有提示框改成同一种颜色。长文章里也不宜连续堆叠提示框，这里集中排列是为了方便对比。

提示框内放代码与步骤

1
2
3
4
5
6
7
8
9

{{< admonition type="example" title="新建草稿" >}}
1. 在项目根目录执行：

   ```sh
   ./scripts/hugo.sh new content posts/my-note.md
   ```

2. 填写标题，保持 `draft: true`，先完成正文。
{{< /admonition >}}

这里代码属于列表第一步，因此需要缩进。短代码开始、结束行独占一行，正文中的代码围栏前后留空行，可以减少嵌套时的排版问题。

类型选择速查

这些类型直接来自固定版本的 layouts/_partials/plugin/admonition.html。升级时若出现变化，应以新版本源码为准。

原生折叠 details

1
2
3
4
5

{{< details summary="展开查看检查清单" open=false >}}
- 检查错别字
- 检查代码复制结果
- 检查手机阅读效果
{{< /details >}}

summary 是折叠标题，open 控制初始状态。给多个 details 相同的 name，可在支持的浏览器中组成互斥展开的组。title 是元素提示文字，不替代 summary。

标签页 tabs / tab

1
2
3
4
5
6
7
8

{{< tabs defaultTab=0 type="underline" placement="top" >}}
{{% tab title="写作" %}}
先用 **Markdown** 写正文，再加入短代码。
{{% /tab %}}
{{% tab title="预览" %}}
运行 `hugo server --bind 127.0.0.1 --disableFastRender`。
{{% /tab %}}
{{< /tabs >}}

defaultTab 从 0 开始；placement 可为 top、bottom、start、end；type="underline" 使用下划线样式。每个 tab 必须直接放在 tabs 内。

这里外层使用尖括号形式，内层 tab 使用百分号形式，使面板中的 Markdown 经 Hugo 渲染。该版本 tab.html 直接输出内部 HTML，不能假设尖括号形式会自动解析面板中的 Markdown。

用同一组折叠做问答

1
2
3
4
5
6
7

{{< details summary="为什么预览能看到，构建后看不到？" name="writing-faq" >}}
先检查文章是否为草稿，以及日期是否晚于构建时间。
{{< /details >}}

{{< details summary="图片为什么显示不出来？" name="writing-faq" >}}
检查路径大小写，以及 URL 是否误写了 `static/` 前缀。
{{< /details >}}

支持原生 details 分组的浏览器，会在打开一个项目时关闭同名组里的另一个。旧浏览器可能允许同时展开，但问答内容仍可阅读。不要给不同章节的独立问答误用相同 name。

在标签页里比较配置格式

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

{{< tabs defaultTab=1 type="underline" placement="top" >}}
{{% tab title="TOML" %}}
```toml
[params]
collection_list = true
collection_navigation = true
```
{{% /tab %}}
{{% tab title="YAML" %}}
```yaml
params:
  collection_list: true
  collection_navigation: true
```
{{% /tab %}}
{{< /tabs >}}

1
2
3

[params]
collection_list = true
collection_navigation = true

1
2
3

params:
  collection_list: true
  collection_navigation: true

defaultTab=1 默认选中第二个面板。本项目实际使用 TOML；YAML 面板仅展示对应写法，不需要把两份配置同时放进项目。

什么时候不该折叠

关键前提、必须执行的步骤和最终结论，最好直接放在正文中。折叠适合故障细节、长日志和补充推导；标签页适合几个互相替代的方案，不适合依次执行的步骤。

发布前应实际点击每个标签和折叠项，并确认面板里的代码可以复制。还要用键盘 Tab 键检查控件是否可聚焦，避免只在鼠标操作下看起来正常。

居中引用 center-quote

1
2
3

{{< center-quote >}}
把经历写下来，让想法有迹可循。
{{< /center-quote >}}

把经历写下来，让想法有迹可循。

该短代码不需要额外参数，适合短引文，不宜包裹长篇段落。

version：标注版本信息

1

{{< version "1.0.0-beta.3" "new" >}}

第一个位置参数是版本号，第二个参数是状态，可用 new、changed、deleted、deprecated。默认链接由主题的 repo_version.url 与版本号拼接而成；此处链接到 主题对应发布版本。

版本标记表达的是文章中的版本说明，不会自动安装或更新主题。当前站点真正的主题锁定来自 Git submodule 的提交记录。

timeline：按时间组织记录

1
2
3
4
5
6
7
8
9

{{< timeline reverse=false placement="bottom" >}}
events:
  - timestamp: "2026-10-01"
    content: "整理写作主题，列出最常查询的语法。"
  - timestamp: "2026-10-08"
    content: "补充源码和渲染效果，检查手机布局。"
  - timestamp: "2026-10-13"
    content: "将文章整理为五篇专题，形成可持续维护的手册。"
{{< /timeline >}}

• 整理写作主题，列出最常查询的语法。
  2026-10-01
• 补充源码和渲染效果，检查手机布局。
  2026-10-08
• 将文章整理为五篇专题，形成可持续维护的手册。
  2026-10-13

内容是 YAML 数据：顶层为 events，每个事件有 timestamp 和 content。日期使用带引号的 ISO 格式，便于排序。reverse=true 可把较新的记录排在前面；placement 控制时间戳的位置。

时间线适合回顾阶段性变化，不适合代替任务清单。如果每一项都是“接下来要做什么”，请使用任务清单。

给短代码准备稳定的数据

复杂短代码通常由“容器参数”和“内部内容”两部分组成。先让一个最小例子正常渲染，再增加事件、图注或其他参数，排查问题会更直接。

本手册优先演示不需要第三方账号、令牌或个人数据的短代码。音视频、地图等组件可以按文章需要再引入，避免每篇笔记都承担额外资源加载。

文件树 file-tree：说明目录结构

文件树适合展示文章包、配置目录和项目结构。相比截图，读者可以复制名称，还能展开或折叠目录。手册演示使用内联数据，不扫描实际项目目录。

可复制源码：

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

{{< file-tree level=2 folder_slash=true >}}
- name: my-note
  type: dir
  children:
    - name: index.md
      type: file
    - name: cover.webp
      type: file
    - name: images
      type: dir
      children:
        - name: diagram.png
          type: file
{{< /file-tree >}}

实际效果：

内容来源的优先级是内联内容、资源文件、数据文件、文件系统。建议文档优先使用内联数据，确保示例不会随着工作目录内容变化。单纯想展示可复制的目录文本，也可以直接使用普通代码块。

链接卡片 link：突出一个参考入口

段落中的普通引用优先使用 Markdown 链接；需要强调文档、工具或站点入口时，再使用卡片。下面显式指定图标，避免为了展示图标而在构建时请求远程 favicon。

1
2
3
4
5
6
7

{{< link
  href="https://gohugo.io/"
  content="Hugo 官方文档"
  title="查看内容组织、模板和构建说明"
  card=true
  card-icon="fa-solid fa-book"
>}}

card-icon 是这个短代码的参数名，不应机械改成 card_icon。同一段不要堆叠过多卡片；一组长期维护的网站入口更适合放入本站的链接页数据。

原始 HTML raw：保留少量自定义标记

只有 Markdown 或现有短代码无法表达时，再使用 raw。例如，希望在一句话里保留 HTML 的键盘按键标记：

1

保存文件：{{< raw "span" >}}<kbd>⌘</kbd> + <kbd>S</kbd>{{< /raw >}}

保存文件：⌘ + S

第一个位置参数指定外层 HTML 标签，默认是 div。放在段落中时选 span，避免把块级元素塞进一行文字。raw 中的 Markdown 标记不会自动变成加粗或列表；需要自行写 HTML。

不要将不可信的脚本或整页 HTML 粘贴进文章。可以用标准 Markdown 表达的内容，继续使用标准语法，后续迁移和维护更轻松。

常用 Shortcodes 选择表

图片与代码见富文本写作，公式与图表见数学公式与可视化图表。这些内容各自维护在对应专题，避免同一份示例出现多个不一致版本。

以上参数以本站固定版本的短代码源码为准。官方参考：扩展短代码、文件树。