可运行示例

这一章是什么

多数文档站在正文里贴一段代码，再贴一段「预期输出」——两段都是手写的，改了一处忘了另一处，读者按文档抄却跑不出同样的结果。

本站把这件事反过来做：示例就是一个真实模板。

• 实现在 layouts/：themes/hugo-docs-theme/layouts/partials/examples/<命名空间>/<名字>.html，里面就是普通的 Hugo 模板，正常调用函数、正常输出 HTML；
• 声明在 content/：页面 front matter 里的 [[params.examples]] 说明「用哪个模板、传什么参数、面板标题与说明」，正文里用一行 {{< examples >}} 决定它出现在哪儿；
• 面板上下两半：上半是这个文件的源码（构建时用 os.ReadFile 读出，不是抄的），下半是执行同一个文件得到的结果。代码与产物不可能漂移；
• 两个出口同源：页面的 Markdown 版本（URL 后接 index.md）会带上同样的模板源码与实际输出，人类与 AI 看到的是同一份事实。

因此，示例也是可验证的：模板写错、参数传错，构建直接失败——不会出现「文档里写得对、实际跑不出来」。

本站有哪些示例

目前共 9 个可运行示例，分布在 9 个页面、2 个章节里。每个示例的模板都在 layouts/partials/examples/ 下，输出由构建时现场执行产出。

方法

• Summary 真实页面上的 .Summary 与 .Description

函数

• cast.ToString 把数字与布尔值转成字符串
• time.Format 给文章加一行时间（本站配置下真实执行）
• collections.First 只显示前 2 篇
• transform.Markdownify 渲染 front matter 里的 Markdown
• strings.ReplaceRE 压缩连续短横与空白（本站真实执行）
• collections.Uniq 标签去重后再排序
• collections.Where 用 dict 切片跑通 where
• strings.Truncate 给卡片标题限长：默认省略号、显式空省略号、安全 HTML

给一页加一个示例（三步）

第 1 步：写模板。新建 themes/hugo-docs-theme/layouts/partials/examples/<命名空间>/<名字>.html，例如 examples/strings/truncate-card-title.html：

{{ $title := .args.title | default "…" }}
<p>{{ $title | strings.Truncate 12 }}</p>

约定：

• 上下文是 dict "args" <声明里的 args> "page" <当前页面>，所以参数用 .args.xxx 读，页面数据用 .page；
• 模板里的第一行注释会被原样展示，写示例时保持源码干净、便于阅读；
• 参数建议给 default，这样声明里不写 args 也能跑。

第 2 步：在内容页 front matter 里声明（放在所有标量字段与其它表之后）：

[[params.examples]]
id    = "strings/truncate-card-title"   # 对应 partials/examples/<id>.html
title = "给卡片标题限长"                 # 面板标题
args  = { size = 12, title = "…" }      # 传给模板的输入
note  = "面板下方的说明，支持 Markdown。" # 可选

第 3 步：在正文里放一行短代码，决定它出现在哪儿：

{{< examples >}}

hugo --ignoreCache --renderToMemory 退出码为 0、且面板里出现了预期输出，就算接好了。

相关章节

• 短代码：文档页里最早的一批「真实产物」演示，用的是 demo 短代码；
• 渲染钩子：钩子产物的现场对照；
• 函数 与方法：可运行示例的主要落点。