Hugo 短代码中的 .Site详解 SHORTCODE.Site 方法及 Site 对象全能力【免费下载链接】hugoThe world’s fastest framework for building websites.项目地址: https://gitcode.com/gh_mirrors/hu/hugo导读在 Hugo 短代码Shortcode模板中SHORTCODE.Site是获取当前站点Site对象的统一入口它返回包裹后的page.siteWrapper对象让你在短代码内部也能访问站点的标题、配置参数、页面集合、菜单、多语言信息等全部站点级数据。本文以 Hugo 官方方法参考页为基础结合源码实现hugolib/shortcode.go 与 resources/page/site.go讲解其用法、返回类型、Site 接口的完整方法清单与实战示例帮助你在自定义短代码中正确、高效地使用站点数据。SHORTCODE.Site 是什么在短代码上下文中.Site代表当前正在渲染的站点。它的官方签名与返回类型如下项目值方法名SHORTCODE.Site签名SHORTCODE.Site返回类型page.siteWrapper从源码可以确认其调用链。在 hugolib/shortcode.go#L113-L116 中// Site returns information about the current site. func (scp *ShortcodeWithPage) Site() page.Site { return scp.Page.Site() }也就是说短代码的.Site最终委托给当前页面Page的Site()方法返回两者指向同一个站点对象——因此在短代码中访问的.Site与页面模板Layout中访问的.Site是等价的。基本用法文档给出的最小示例是在短代码模板中输出站点标题{{ .Site.Title }}把这段代码放入layouts/shortcodes/下的任意短代码模板例如layouts/shortcodes/sitetitle.html然后在内容文件中通过{{ sitetitle }}或{{% sitetitle %}}调用即可在页面中渲染出config配置里title字段的值。由于返回对象是站点级数据容器它支持的远不止标题所有 Site methods 都可以通过.Site链式调用。返回类型 siteWrapper 与 Site 接口的源码印证文档标注的返回类型page.siteWrapper定义在 resources/page/site.go#L161-L170type siteWrapper struct { s Site } func WrapSite(s Site) Site { if s nil { panic(Site is nil) } return siteWrapper{s: s} }siteWrapper是一个薄包装器内部持有一个Site接口实例并将方法逐一转发。它实现了 resources/page/site.go#L37-L138 中定义的完整Site接口同时额外实现了identity.ForEeachIdentityByNameProvider见 resources/page/site.go#L158-L159供 Hugo 内部的依赖追踪使用。对模板作者而言可以把.Site理解为当前站点的只读快照无论站点如何被包装最终调用都会落到同一份站点数据上。Site 接口的完整方法清单Site接口是.Site可用方法的权威依据。按功能分类如下方法名后为返回值类型均见 resources/page/site.go#L37-L138站点基本信息Title()→string站点标题等价于配置中的titleBaseURL()→string站点基地址Copyright()→string版权信息Lastmod()→time.Time内容最后修改时间ServerPort()→inthugo server的监听端口Hugo()→HugoInfo构建信息结构体Config()→SiteConfig站点配置String()→string站点字符串表示不保证稳定站点配置与数据Params()→hmaps.Params站点[params]配置Param(key any)→(any, error)按键查询参数支持点路径如.Site.Param foo.barData()→map[string]anydata/目录下所有数据文件的合并结果Store()→*hstore.Scratch站点级临时存储页面集合Pages()→Pages本站全部页面RegularPages()→Pages本站全部普通内容页AllPages()→Pages所有语言下的全部页面Sections()→Pages顶层栏目SectionHome()→Page首页页面对象GetPage(ref ...string)→(Page, error)按引用路径解析页面MainSections()→[]string主要栏目路径列表多语言与多站点Language()→*langs.Language当前语言对象含Lang、Locale、Weight等字段Languages()→langs.Languages全部已配置语言LanguagePrefix()→string当前语言的前缀如/zh/Sites()→Sites全部站点各语言各维度Current()→Site当前正在渲染的站点IsDefault()→bool是否为默认站点Dimension(string)→SiteDimension按语言/版本/角色维度获取站点Role()→roles.Role站点角色Version()→versions.Version站点版本导航与分类Menus()→navigation.Menus站点菜单Taxonomies()→TaxonomyList分类Taxonomy映射已弃用方法BuildDrafts()→bool已弃用将在未来版本移除LanguageCode()→string已弃用应改用.Site.Language.Locale见下文实战示例1. 输出站点标题与版权layouts/shortcodes/sitefooter.htmlfooter p{{ .Site.Title }} copy; {{ now.Year }}/p /footer2. 读取站点自定义参数假设hugo.toml中配置了[params] author Hugo Dev github https://github.com/gohugoio短代码中读取{{ with .Site.Params.author }} meta nameauthor content{{ . }} {{ end }}3. 遍历站点菜单ul {{ range .Site.Menus.main }} lia href{{ .URL }}{{ .Name }}/a/li {{ end }} /ul4. 多语言场景下输出当前语言html lang{{ .Site.Language.Lang }}注意官方文档特别提示.Site.LanguageCode已弃用。源码 resources/page/site.go#L228-L231 中可以看到它会在调用时输出弃用警告并建议改用.Site.Language.Localefunc (s *siteWrapper) LanguageCode() string { hugo.DeprecateWithLogger(.Site.LanguageCode, Use .Site.Language.Locale instead., v0.158.0, s.s.Language().Logger()) return s.s.Language().Locale() }5. 在短代码中解析页面引用{{ $page : .Site.GetPage /about }} {{ if $page }}a href{{ $page.RelPermalink }}{{ $page.Title }}/a{{ end }}使用注意作用域SHORTCODE.Site在短代码模板中以.Site形式访问等价于页面模板中的.Site二者指向同一站点对象。只读访问siteWrapper仅提供读取方法站点数据由 Hugo 构建引擎统一管理模板侧不应尝试修改。已弃用 API.Site.LanguageCode与.Site.BuildDrafts均为弃用状态新代码请分别使用.Site.Language.Locale与不依赖构建标志的写法。延伸阅读站点方法总览Site methods 索引各方法独立参考页Title、Params、Param、Menus、Language、Languages、Data、GetPage、Pages、RegularPages、AllPages、Sections、Home、Sites、Taxonomies、Config、Hugo、BaseURL、Store 等页面上的.Site方法Page.Site 参考页源码实现ShortcodeWithPage.Site()、Site 接口与 siteWrapper【免费下载链接】hugoThe world’s fastest framework for building websites.项目地址: https://gitcode.com/gh_mirrors/hu/hugo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
