Summary
返回给定页面的摘要。
这一页解决什么问题
列表页要显示每篇文章的开头一段(生成 <meta name="description">、做卡片摘要),.Summary 就是这份「摘要 HTML」。它有三种来源,优先级依次是:
- 手动摘要:正文里的 `
分隔符之前的全部内容; 2. **前置元数据摘要**:front matter 里的summary 字段; 3. **自动摘要**:[summaryLength`](/configuration/all/) 决定的字数截断。
实测这三条规则确实按此顺序生效(见下表)。想看「摘要是不是比正文短」,用 .Truncated。
什么时候用,什么时候别用
该用:
- 列表页/卡片显示摘要,并配合
.Truncated决定是否显示「阅读更多」; - SEO:把摘要塞进
<meta name="description">(需要先plainify)。
别用:
- 想要完整正文 → 用
.Content; - 想要纯文本摘要 →
.Summary是 HTML,需要{{ .Summary | plainify }}; - 想自己控制截断长度 → 用
<!--more-->或 front mattersummary,自动摘要的长度在站点配置里改; - 想要不含摘要的正文(例如 RSS 全文)→ 用
ContentWithoutSummary。
用法
你可以手动定义[摘要][],也可以在前置元数据中定义,或者让它自动生成。手动摘要优先于前置元数据摘要,前置元数据摘要优先于自动摘要。
要在列出某个 section 中的页面时,在每个链接下方附上摘要:
{{ range .Pages }}
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ .Summary }}
{{ end }}取决于内容长度和摘要的定义方式,摘要可能等同于内容本身。要判断内容长度是否超过摘要长度,请使用 Page 对象上的 Truncated 方法。这在需要有条件地渲染“阅读更多”链接时很有用:
{{ range .Pages }}
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ .Summary }}
{{ if .Truncated }}
<a href="{{ .RelPermalink }}">Read more...</a>
{{ end }}
{{ end }}完整示例:三种摘要来源对照
测试站的三个内容文件:
<!-- content/posts/bundle-1/index.md(用 <!--more--> 手动分隔) -->
叶子包的开场段落。
<!--more-->
## 包内标题
包内正文。# content/posts/summary-front.md(前置元数据摘要)
summary = "手写摘要。"<!-- content/posts/post-2.md(没有分隔符、也没有 summary) -->
第二篇正文,只有一小段。列表模板:
{{ range .RegularPages }}
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ .Summary }}
{{ if .Truncated }}<a href="{{ .RelPermalink }}">阅读更多</a>{{ end }}
{{ end }}实测(Hugo 0.167.0):
| 页面 | .Summary 的值 |
.Truncated |
|---|---|---|
/posts/bundle-1/ |
<p>叶子包的开场段落。</p> |
true |
/posts/post-1/(有 <!--more-->) |
<p>第一篇的开场段落。</p> |
true |
/posts/summary-front/(front matter summary) |
手写摘要。 |
false |
/posts/post-2/(短内容、无分隔符) |
<p>第二篇正文,只有一小段。</p> |
false |
/posts/empty-body/(正文为空) |
空字符串 | false |
你应当看到什么:手动分隔符与自动摘要都带 <p> 包裹,而 front matter 的 summary 原样输出(手写摘要。 没有 <p>);前三种情况下 .Truncated 只有「内容确实被截断」时才为 true。
本站实跑:真实页面上的 .Summary
示例模板examples/methods/page-summary-vs-description.html
{{- $path := .args.path | default "/getting-started/quick-start/" -}}
{{- with site.GetPage $path }}
<p>页面:<a href="{{ .RelPermalink }}">{{ .Title }}</a></p>
<p><code>description</code>:{{ .Description }}</p>
<p><code>.Summary | plainify</code>:{{ .Summary | plainify }}…</p>
<p>字数:{{ .WordCount }} · 预计阅读:{{ .ReadingTime }} 分钟</p>
{{- else }}
<p>找不到页面:{{ $path }}</p>
{{- end }}实际输出构建时由上面这份模板真跑出来的
页面:快速开始
description:手把手从零跑通第一个 Hugo 站点:装好环境、创建项目、写第一篇内容、在浏览器里看到它,最后发布成静态文件。每一步都给验证方法。
.Summary | plainify:这一页的目标只有一个:让你在半小时内,在自己电脑上真正跑起来一个 Hugo 站点,而不是读完一堆概念。走完之后你会有一个能看的本地站点、一篇自己写的文章,以及一个可以上传到任何静态托管平台的 public/ 目录。
…
字数:3582 · 预计阅读:8 分钟
上表那个 fixture 例子需要专门的测试内容;这一条跑的是本站真实页面,由 site.GetPage 取到后现场读取属性。
模板用 site.GetPage 取到本站一个真实页面,再现场读它的 description、.Summary、.WordCount 与 .ReadingTime——也就是列表页拿到的同一份数据。
返回值边界(实测)
| 情况 | 结果 | 是否报错 |
|---|---|---|
正文含 <!--more--> |
分隔符之前的 HTML(实测带 <p>) |
否 |
front matter 有 summary |
该字符串原样(实测无 <p>) |
否 |
| 都没有、内容很短 | 自动摘要 = 全部内容,.Truncated 为 false |
否 |
| 正文为空 | 空字符串(实测) | 否 |
| 返回类型 | template.HTML(输出不转义) |
否 |
| 想要纯文本 | 需自行 plainify |
否 |
更多排查入口见故障排查。