# Shortcodes 与组件


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

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

<!--more-->

## 先学会安全展示源码

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

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

## 提示框 admonition

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

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

| 参数      | 作用                                      |
| ------- | --------------------------------------- |
| `type`  | 提示类型，例如 `note`、`tip`、`warning`、`danger` |
| `title` | 自定义标题，支持 Markdown                       |
| `open`  | 布尔值，`false` 时默认折叠                       |

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

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

## 短代码与 Markdown 怎么配合

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

| 写法          | 适用范围                  | 本手册中的例子                        |
| ----------- | --------------------- | ------------------------------ |
| 普通 Markdown | 标题、段落、列表、代码           | 大多数正文                          |
| 尖括号短代码      | 由短代码模板组织输出            | `admonition`、`details`、`image` |
| 百分号短代码      | 需要 Markdown 继续处理输出的场景 | `tabs` 中的 `tab`                |

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

## 一组不同语义的提示

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

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

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

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

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

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

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

## 提示框内放代码与步骤

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

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

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

{{< admonition type="example" title="新建草稿" >}}

1. 在项目根目录执行：
   ```sh
   ./scripts/hugo.sh new content posts/my-note.md
   ```
2. 填写标题，保持 `draft: true`，先完成正文。  
   {{< /admonition >}}

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

## 类型选择速查

| 类型              | 适合表达      | 示例标题      |
| --------------- | --------- | --------- |
| `note` / `info` | 中性补充信息    | 适用范围、背景说明 |
| `tip`           | 可选的改进建议   | 写作提示      |
| `warning`       | 容易遗漏的前提   | 发布前检查     |
| `danger`        | 需要明确注意的行为 | 覆盖范围      |
| `success`       | 已完成的结果    | 检查完成      |
| `question`      | 需要思考的问题   | 为什么使用合集   |
| `example`       | 示范或练习     | 新建草稿      |

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

## 原生折叠 details

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

{{< details summary="展开查看检查清单" open=false >}}

- 检查错别字
- 检查代码复制结果
- 检查手机阅读效果  
  {{< /details >}}

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

## 标签页 tabs / tab

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

{{< 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。

## 用同一组折叠做问答

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

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

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

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

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

## 在标签页里比较配置格式

````text
{{</* 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 */>}}
````

{{< 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 >}}

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

## 什么时候不该折叠

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

| 内容           | 更合适的组织方式  |
| ------------ | --------- |
| 所有人都要执行的三步操作 | 有序列表      |
| 只在失败时需要的排查信息 | 折叠        |
| 同一配置的两种格式    | 标签页       |
| 决定能否继续的重要前提  | 正文或展开的提示框 |

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

## 居中引用 center-quote

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

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

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

## version：标注版本信息

```text
{{</* version "1.0.0-beta.3" "new" */>}}
```

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

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

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

## timeline：按时间组织记录

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

{{< timeline reverse=false placement="bottom" >}}  
events:

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

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

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

## 给短代码准备稳定的数据

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

| 检查点        | 例子                        |
| ---------- | ------------------------- |
| 参数是否属于当前版本 | 对照 `layouts/_shortcodes/` |
| 成对标签是否闭合   | `timeline` 和 `/timeline`  |
| 内部数据格式是否正确 | YAML 缩进、JSON 引号           |
| 演示源码是否转义   | 代码围栏里的短代码也要转义             |
| 是否依赖外部内容   | 外部视频、地图和远程图片可能需要网络        |

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

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

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

可复制源码：

```text
{{</* 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 */>}}
```

实际效果：

{{< 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 >}}

| 参数或字段 | 说明 |
| --- | --- |
| `level` | 初始展开层级；`0` 全部折叠，`-1` 全部展开 |
| `folder_slash` | 为目录名显示末尾斜杠，使用当前版本的下划线写法 |
| `name` / `type` | 节点名称及类型，类型为 `dir` 或 `file` |
| `children` | 目录下的子节点列表，注意 YAML 缩进 |
| `file` | 从页面资源或 assets 中读取 JSON、YAML、TOML 数据 |
| `data` | 从 `data/filetree/` 中读取指定数据 |
| `path` | 扫描文件系统目录；静态示例通常不需要 |

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

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

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

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

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

| 参数 | 说明 |
| --- | --- |
| `href` | 链接目的地址，站内页面可以使用 `/posts/.../` |
| `content` | 展示的链接文字 |
| `title` | 鼠标悬停时的补充说明 |
| `card` | 是否使用卡片样式 |
| `card-icon` | 卡片图标，可使用主题支持的 Font Awesome 类名 |

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

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

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

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

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

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

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

## 常用 Shortcodes 选择表

| 写作需求 | 推荐写法 | 注意事项 |
| --- | --- | --- |
| 提示、警告、补充说明 | `admonition` | 根据内容选择语义，不只按颜色选择 |
| 收起较长的补充内容 | `details` | 关键结论留在外面 |
| 比较多种语言或配置 | `tabs` / `tab` | 标签名称明确，同组内容结构一致 |
| 展示目录结构 | `file-tree` | 优先用稳定的内联示例数据 |
| 强调参考入口 | `link` | 普通段落引用仍用 Markdown 链接 |
| 居中引用 | `center-quote` | 适合短句，不适合大段正文 |
| 标注版本变化 | `version` | 确认版本链接指向正确项目 |
| 按时间记录事件 | `timeline` | 保持时间格式一致 |
| 少量原始 HTML | `raw` | 避免替代整篇文章的 Markdown 排版 |

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

以上参数以本站固定版本的短代码源码为准。官方参考：[扩展短代码](https://fixit.lruihao.cn/zh-cn/docs/content-management/shortcodes/extended/introduction/)、[文件树](https://fixit.lruihao.cn/zh-cn/docs/content-management/shortcodes/extended/file-tree/)。


---

> 作者: [yuehei](/authors/yuehei/)  
> URL: https://33.ax/wiki/fixit-shortcodes/