Hugo 短代码中的 .Site：详解 SHORTCODE.Site 方法及 Site 对象全能力-迪斯科星球

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-L170：

type 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：站点标题，等价于配置中的title
BaseURL()→string：站点基地址
Copyright()→string：版权信息
Lastmod()→time.Time：内容最后修改时间
ServerPort()→int：hugo server的监听端口
Hugo()→HugoInfo：构建信息结构体
Config()→SiteConfig：站点配置
String()→string：站点字符串表示（不保证稳定）

站点配置与数据

Params()→hmaps.Params：站点[params]配置
Param(key any)→(any, error)：按键查询参数，支持点路径（如.Site.Param "foo.bar"）
Data()→map[string]any：data/目录下所有数据文件的合并结果
Store()→*hstore.Scratch：站点级临时存储

页面集合

Pages()→Pages：本站全部页面
RegularPages()→Pages：本站全部普通内容页
AllPages()→Pages：所有语言下的全部页面
Sections()→Pages：顶层栏目（Section）
Home()→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.html：

<footer> <p>{{ .Site.Title }} &copy; {{ now.Year }}</p> </footer>

2. 读取站点自定义参数

假设hugo.toml中配置了：

[params] author = "Hugo Dev" github = "https://github.com/gohugoio"

短代码中读取：

{{ with .Site.Params.author }} <meta name="author" content="{{ . }}"> {{ end }}

3. 遍历站点菜单

<ul> {{ range .Site.Menus.main }} <li><a href="{{ .URL }}">{{ .Name }}</a></li> {{ end }} </ul>

4. 多语言场景下输出当前语言

<html lang="{{ .Site.Language.Lang }}">

注意：官方文档特别提示，.Site.LanguageCode已弃用。源码 resources/page/site.go#L228-L231 中可以看到它会在调用时输出弃用警告，并建议改用.Site.Language.Locale：

func (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与不依赖构建标志的写法。

企业官网建设流程全解析