文档章节
Site 方法
在 Site 对象上使用这些方法。
这一页解决什么问题
Site 对象(模板里的 .Site 或 site)代表当前站点:它是哪个语言、哪个版本、哪个角色,叫什么名字,有哪些页面、栏目、菜单、分类法,以及配置里写了什么。
本章的 27 个方法可以归纳成六类:
- 站点标识与配置:
Title、Copyright、BaseURL、Params、Param、Config; - 时间与数据:
Lastmod、Data; - 页面集合:
Home、Pages、RegularPages、Sections、MainSections、GetPage; - 导航与分类法:
Menus、Taxonomies; - 维度(语言 / 版本 / 角色):
Language、LanguagePrefix、Languages、Version、Role、Dimension、IsDefault、Sites; - 跨模板共享数据:
Store。
写 base 模板、页头页脚、导航、语言或版本切换器时,几乎都要从这一章挑方法。
读完本章你应该能够
- 分清
Params/Param/Config各读的是配置里的哪一部分,并说明为什么[params]与[services]要用不同方法读; - 在
Pages、RegularPages、Sections之间做出选择,并知道Pages会混进首页与分类法页面; - 用
MainSections写出不硬编码栏目名的首页列表,并知道未配置时的回退规则; - 用
GetPage按路径取页面,并为「路径不存在返回nil」写好兜底; - 用
Menus渲染导航并高亮当前项,知道为什么这里不能用partialCached; - 说清
Taxonomies的三层结构与「未配置 vs 配置了但没术语」在len上的差别; - 用
Language/Version/Role/Dimension/IsDefault处理多语言、多版本、多角色站点; - 用
Store在 partial、shortcode 与父模板之间传递数据,并知道它的生命周期只有一次构建。
什么时候用本章的方法,什么时候别用
该用:
- 需要站点级信息或集合(站点名、全部文章、栏目、菜单、分类法、当前语言);
- 模板要在多语言/多版本/多角色矩阵里正确工作。
别用:
- 需要页面级信息(标题、日期、参数、上下篇、资源)→ 用 methods/page;
- 需要集合的排序、分组、分页 → 用 methods/pages 上的方法(如
ByTitle、GroupBy、Paginate); - 需要时间加减与格式化 → 用 methods/time 与 functions/time;
- 需要分类法页面内的术语排序 → 用 methods/taxonomy 的
Alphabetical/ByCount。
本章里最容易混的四对同名前缀:Params 与 Param(整张表 vs 查一个键)、Pages 与 RegularPages(全部 kind vs 只要常规页面)、Sections 与 MainSections(页面对象 vs 字符串切片)、Language 与 Languages(当前语言 vs 语言集合)。
阅读顺序
按「先认站点 → 再取内容 → 后处理维度」用:
- 站点是谁:Site.Title → Site.Copyright → Site.BaseURL → Site.Params → Site.Param → Site.Config
- 内容与时间:Site.Home → Site.Pages → Site.RegularPages → Site.Sections → Site.MainSections → Site.GetPage → Site.Lastmod → Site.Data
- 导航与分类:Site.Menus → Site.Taxonomies
- 语言、版本与角色:Site.Language → Site.LanguagePrefix → Site.Version → Site.Role → Site.Dimension → Site.IsDefault → Site.Languages → Site.Sites
- 共享数据:Site.Store
- 已弃用(了解即可):Site.AllPages → Site.BuildDrafts
只想先跑起来,走 1 → 2 即可;做多语言或文档版本站时再回来看第 4 组。
一个能跑通的最小示例
在最小站点(title = 'My Documentation Site',content/books/ 4 页、content/films/ 3 页,mainSections = ['books','films'])的 home 模板里:
layouts/index.htmlgo-html-template
<h1>{{ .Site.Title }}</h1>
<p>共 {{ len .Site.RegularPages }} 篇,{{ len .Site.Sections }} 个栏目</p>
{{ range where .Site.RegularPages "Section" "in" .Site.MainSections }}
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ end }}Hugo 渲染为(range 的空白已省略):
html
<h1>My Documentation Site</h1>
<p>共 7 篇,2 个栏目</p>
<h2><a href="/films/film-3/">Film Three</a></h2>
<h2><a href="/films/film-2/">Film Two</a></h2>
<h2><a href="/films/film-1/">Film One</a></h2>
<h2><a href="/books/pride-and-prejudice/">Pride and Prejudice</a></h2>
<h2><a href="/books/jamaica-inn/">Jamaica Inn</a></h2>
<h2><a href="/books/death-on-the-nile/">Death on the Nile</a></h2>
<h2><a href="/books/and-then-there-were-none/">And Then There Were None</a></h2>你应当看到什么:Site.Title 直接来自配置;RegularPages 只数文章(7,不含栏目与分类法页面);where … "in" .Site.MainSections 让栏目名完全由配置决定——这就是本章要解决的核心问题。
本章内容
- AllPages 返回所有语言中所有页面的集合。 (今天)
- BaseURL 返回项目配置中定义的 base URL。 (今天)
- BuildDrafts 报告当前构建是否启用了草稿发布。 (今天)
- Config 返回项目配置的一个子集。 (今天)
- Copyright 返回项目配置中定义的版权声明。 (今天)
- Data 返回由 data 目录中的文件构成的数据结构。 (今天)
- Dimension 返回给定站点中指定维度的维度对象。 (今天)
- GetPage 返回给定路径对应的 Page 对象。 (今天)
- Home 返回给定站点的首页 Page 对象。 (今天)
- IsDefault 报告给定站点在所有维度上是否为默认站点。 (今天)
- Language 返回给定站点的 Language 对象。 (今天)
- LanguagePrefix 返回给定站点的 URL 语言前缀(如果有)。 (今天)
- Languages 返回所有站点的语言对象集合,按语言权重排序。 (今天)
- Lastmod 返回站点内容的最后修改日期。 (今天)
- MainSections 返回项目配置中定义的主要 section 名称切片,若未定义则回退到包含页面最多的顶层 section。 (今天)
- Menus 返回给定站点的菜单对象集合。 (今天)
- Pages 返回所有页面的集合。 (今天)
- Param 返回给定 key 对应的站点参数。 (今天)
- Params 返回项目配置中定义的自定义参数映射。 (今天)
- RegularPages 返回所有常规页面的集合。 (今天)
- Role 返回给定站点的 Role 对象。 (今天)
- Sections 返回顶层 section 页面的集合。 (今天)
- Sites 返回所有维度的所有站点组成的集合。 (今天)
- Store 返回一个持久化的数据结构,用于存储和操作带 key 的值,作用域为当前站点。 (今天)
- Taxonomies 返回一个数据结构,其中包含站点的 Taxonomy 对象、每个 Taxonomy 对象中的术语,以及术语所归属的页面。 (今天)
- Title 返回项目配置中定义的标题。 (今天)
- Version 返回给定站点的 Version 对象。 (今天)