跳转到主要内容

提示块

用 > [!NOTE] 这样的块引用写出带颜色、图标与标题的提示、警告与折叠块，不需要短代码。

提示块（Callout）是 GitHub / Obsidian 风格的块引用：> [!TYPE] 起头，正文跟在后面。用于把提示、警告、前提条件从正文中分离出来；正文一句话能说清的内容不必使用提示块。

最简例子

源码
> [!NOTE]
> Hugo Module 需要本机安装 Go；只用离线归档时不需要。
说明

Hugo Module 需要本机安装 Go；只用离线归档时不需要。

不写标题时使用本地化的类型名（中文站显示「注意」，英文站显示 “Note”）。源码在 GitHub 上按 GitHub 的提示块渲染，在普通 Markdown 阅读器中显示为块引用，内容都不会丢失。

十种类型

前五种与 GitHub 一致，后五种是 OINK 追加的语义类型。每种类型有默认图标与强调色。

源码
> [!TIP]
> 用 `hugo server -D` 可以预览草稿。

> [!IMPORTANT]
> 主题下限是 Hugo Extended 0.160.1，低于它构建直接失败。

> [!WARNING]
> `hugo --cleanDestinationDir` 会清空 `public/`。

> [!CAUTION]
> 删除 `resources/_gen` 后第一次构建会慢很多。

> [!SUCCESS]
> 构建通过、零告警——可以推上线了。

> [!DANGER]
> 不要把 `go.work` 提交进仓库。

> [!QUESTION]
> 站点要不要开评论？看[启用评论](/zh/docs/admin/comments/)。

> [!EXAMPLE]
> `pgsty.com` 就是一个只用了提示块与表格的纯文档站。

> [!QUOTE]
> Documentation is a love letter that you write to your future self.
提示

用 hugo server -D 可以预览草稿。

重要

主题下限是 Hugo Extended 0.160.1，低于它构建直接失败。

警告

hugo --cleanDestinationDir 会清空 public/。

注意

删除 resources/_gen 后第一次构建会慢很多。

成功

构建通过、零告警——可以推上线了。

危险

不要把 go.work 提交进仓库。

问题

站点要不要开评论？看启用评论。

示例

pgsty.com 就是一个只用了提示块与表格的纯文档站。

引用

Documentation is a love letter that you write to your future self.

类型名不区分大小写。

自定义标题

标记同一行的后续文字是标题，支持行内 Markdown（代码、粗体、链接）。

源码
> [!WARNING] 会改写 `public/`
> 生产构建前先确认 `baseURL` 指向正式域名，否则所有绝对链接都会指错。
会改写 public/

生产构建前先确认 baseURL 指向正式域名，否则所有绝对链接都会指错。

正文内容

正文是页面级 Markdown：列表、代码围栏、表格、图片、嵌套的提示块。每一行都以 > 开头，围栏也不例外。

源码
> [!TIP] 三条命令启动预览
>
> 1. 克隆：`git clone https://github.com/pgsty/oink.pgsty.com my-docs`
> 2. 进入目录并预览：
>    ```bash
>    cd my-docs && hugo server
>    ```
> 3. 打开 <http://localhost:1313/>
>
> | 端口 | 用途 |
> | --- | --- |
> | 1313 | Hugo 开发服务器 |
三条命令启动预览
  1. 克隆：git clone https://github.com/pgsty/oink.pgsty.com my-docs
  2. 进入目录并预览： 
    cd my-docs && hugo server
  3. 打开 http://localhost:1313/
端口 用途
1313 Hugo 开发服务器

折叠

类型后加 - 默认收起，加 + 默认展开；两者都渲染为原生 <details>，不加载 JavaScript。适用于完整输出、备选方案、背景说明这类不必默认展示的内容。

源码
> [!NOTE]- 为什么需要 Go？
> Hugo 通过 Go 的模块系统下载主题（`hugo mod get`）。用 submodule 或离线归档时可以不装 Go。

> [!TIP]+ 默认展开，但读者可以收起
> 收起状态不会被记住，刷新后回到默认。
为什么需要 Go？

Hugo 通过 Go 的模块系统下载主题（hugo mod get）。用 submodule 或离线归档时可以不装 Go。

默认展开，但读者可以收起

收起状态不会被记住，刷新后回到默认。

中性折叠块 DETAILS

[!DETAILS] 是没有语义颜色的折叠块：不加符号默认收起，[!DETAILS]+ 默认展开。用于冗长输出、完整配置文件等需要折叠的内容。

源码
> [!DETAILS] 完整的 `hugo version` 输出
> ```text
> hugo v0.164.0+extended+withdeploy darwin/arm64 BuildDate=2026-07-06T16:39:30Z VendorInfo=Homebrew
> ```
完整的 hugo version 输出 
hugo v0.164.0+extended+withdeploy darwin/arm64 BuildDate=2026-07-06T16:39:30Z VendorInfo=Homebrew

自定义图标

块引用结束后的下一行写属性 {icon="fa-solid fa-xxx"}（一对 Font Awesome class），替换该类型的默认图标。属性行紧接块引用，中间不能有空行。

源码
> [!TIP] PostgreSQL 18 已支持
> 从 Pigsty v4 起默认安装 PostgreSQL 18。
{icon="fa-solid fa-database"}
PostgreSQL 18 已支持

从 Pigsty v4 起默认安装 PostgreSQL 18。

嵌套

提示块可以嵌套（每层多一个 >），也可以放在列表项或步骤中。建议最多嵌套一层。

源码
> [!WARNING] 升级前先备份
> 升级主题版本可能改变渲染结果。
>
> > [!TIP]- 怎么备份
> > `git tag pre-upgrade` 就够了——回滚只是 `git checkout pre-upgrade`。
升级前先备份

升级主题版本可能改变渲染结果。

怎么备份

git tag pre-upgrade 就够了——回滚只是 git checkout pre-upgrade。

未知类型与易错写法

未知的类型名不会导致构建失败，也不会丢失内容：该块渲染为普通块引用，[!TYPE] 标记原样可见。

源码
> [!NOTICE] 这不是合法类型
> 标记会保留在页面上提醒你。

[!NOTICE] 这不是合法类型

标记会保留在页面上提醒你。

其它常见问题：

  • 正文与标题合并：经过 Prettier 等格式化工具的文件，在标题行下保留一个空的 > 行，否则工具会把标题并入正文。
  • 属性行被格式化工具移动：把 {icon=…} 这类标记行放在 <!-- prettier-ignore-start --> / <!-- prettier-ignore-end --> 之间。
  • style、onclick 等属性导致构建失败：属性行只接受 icon 与 class（见下表）。

输出形态

输出 呈现
HTML 静态类型是 <div class="td-callout" role="note">；折叠类型是原生 <details> + <summary>
打印 全部静态展开，折叠块带 data-td-callout-collapsible 标记
Markdown 保留源码块引用（含 [!TYPE] 标记与标题）
RSS 与打印相同，静态展开

提示块不加载脚本。

参数参考

标记行 > [!TYPE]± 标题：

TYPE 枚举 default—
NOTE TIP IMPORTANT WARNING CAUTION SUCCESS DANGER QUESTION EXAMPLE QUOTE DETAILS；大小写不敏感；未知值渲染为普通块引用
± - / + / 无 default无
- 折叠默认收起，+ 折叠默认展开；DETAILS 不加符号即收起
标题 行内 Markdown default类型的本地化名称
与标记同一行

属性行 {…}（块引用之后紧接的一行）：

icon Font Awesome class 对 default类型默认图标
例如 fa-solid fa-database；DETAILS 默认无图标
class 空格分隔的 class default—
原样透传给站点 CSS

style、on* 与其它任何键都会让构建失败。

限制与常见问题

  • 不能自定义颜色：颜色由类型决定，需要新语义时选最接近的类型并自定义标题。
  • 折叠状态不持久化。
  • 提示块可以放在 {.steps} 列表项与 {{% steps %}} 步骤中（见步骤），块引用的每一行都以 > 开头，缩进与列表项对齐。
最后修改 2026-08-21 · update website cases (7477980)