Variables and Params - 变量和参数
Hugo的模板是上下文感知的,并为您在创建站点视图时提供大量的可用值。
https://gohugo.io/variables/site/
许多站点范围的变量在站点配置中定义,但是,Hugo提供了许多内置变量,以方便在模板中访问全局值。
以下是站点级别(也称为"全局")变量列表。其中许多变量在站点配置文件中定义,而其他变量则内置于Hugo的核心中,以便在模板中方便使用。
下面的所有方法,例如.Site.RegularPages
也可以通过全局site
函数(例如site.RegularPages
)访问,这在局部文件中 Page
对象不容易获取时可能会很方便。
所有页面的数组,不考虑它们的翻译。
站点配置中定义的站点基本URL。
一个布尔值(默认值为false
),用于指示是否按照站点配置构建草稿。
表示您的站点版权的字符串,即在站点配置中所定义的。
自定义数据,请参阅数据模板。
表示Disqus简码的字符串,即在站点配置文件中所定义的。
表示Google Analytics追踪代码的字符串,即在站点配置文件中所定义的。
指向主页页面对象的引用。
是否在该站点中存在多种语言。有关更多信息,请参见多语言。
一个布尔值,指示是否使用Hugo的内置服务器提供站点。有关更多信息,请参见hugo server。
当前区域设置的语言代码(例如,en
)。
完整的语言名称(例如,English
)。
定义.Site.Languages
列表顺序的权重。
指示当前用于渲染站点的语言。该对象的属性在站点配置语言定义中设置。
表示在站点配置中定义的语言tag的字符串。
可以用于为URL添加前缀以指向正确的语言。即使只定义了一种语言,它也会起作用。另请参见absLangURL和relLangURL函数。
一个按照定义的权重排序的语言列表。
一个表示站点最近更改的日期/时间的字符串。此字符串基于内容页面前置元数据中的date
变量。
站点中的所有菜单。
按日期排序的所有内容的数组,最新的在前面。此数组仅包含当前语言的页面。请参阅.Site.Pages。
一个常规页面集合的快捷方式。.Site.RegularPages
等效于where .Site.Pages "Kind" "page"
。请参阅.Site.Pages。
站点的顶级目录。
整个站点的分类法。另请参阅从任何模板访问分类法数据的章节。
一个表示站点标题的字符串。
.Site.Params
变量 .Site.Params
是一个容器,它保存了来自站点配置params
部分的值。
.Site.Params
以下config.[yaml|toml|json]
定义了一个站点范围的description
参数:
config.
=== “yaml”
``` yaml
baseURL: https://yoursite.example.com/
params:
author: Nikola Tesla
description: Tesla's Awesome Hugo Site
```
=== “toml”
``` toml
baseURL = 'https://yoursite.example.com/'
[params]
author = 'Nikola Tesla'
description = "Tesla's Awesome Hugo Site"
```
=== “json”
``` json
{
"baseURL": "https://yoursite.example.com/",
"params": {
"author": "Nikola Tesla",
"description": "Tesla's Awesome Hugo Site"
}
}
```
您可以在局部模板中使用.Site.Params
调用默认站点描述:
layouts/partials/head.html
|
|
.Site.Pages
与.Pages
比较常规页面是"post"页面或"content"页面。
列表页面可以列出常规页面和其他列表页面。一些示例是:主页、章节页面、分类法(/tags/
)和条目(/tags/foo/)
页面。
.Site.Pages
站点所有页面的集合:常规页面、章节页面、分类法页面等——Superset of everything!
.Site.RegularPages
仅包含常规页面的集合。
上述.Site. ..
页面集合可以从模板的任何作用域中访问。
以下变量仅从当前列表页的作用域返回页面集合:
.Pages
Collection of regular pages and only first-level section pages under the current list page.
在当前列表页面下,包含所有常规页面和只有一级章节页面的集合。
.RegularPages
仅包含当前列表页面下的普通页面的集合。这排除嵌套章节/列表页面中的常规页面(那些是带有 _index.md
文件的子目录)。
.RegularPagesRecursive
包含一个列表页面下的所有普通页面的集合。这包括嵌套章节/列表页面中的常规页面。
注意
从常规页面的作用域来看,
.Pages
和.RegularPages
返回一个空的 slice。
https://gohugo.io/variables/page/
页面级变量定义在内容文件的前置元数据中,从内容文件的位置中派生出来,或从内容本身中提取出来。
以下是页面级变量列表。其中许多将在前置元数据中定义、从文件位置中派生或从内容本身中提取。
包含给定页面的所有备选格式;这个变量在您站点的 <head>
中的 link rel
列表中非常有用。(请参见输出格式(Output Formats)。)
此页面的别名
获取每个页面的祖先,简化 面包屑导航(breadcrumb navigation) 实现的复杂性。
bundle类型: leaf
, branch
, 或者如果页面不是bundle,则为空字符串。
内容本身,在前置元数据下定义。
特定于此页面类型的数据。
与页面相关联的日期;.Date
从内容的前置元数据中的date
字段获取。还请参见.ExpiryDate
、.PublishDate
和.Lastmod
。
此页面的描述。
一个布尔值,如果内容在前置元数据中标记为草稿,则为 true
。
内容计划过期的日期;.ExpiryDate
从内容的前置元数据中的expirydate
字段获取。还请参见.PublishDate
、.Date
和.Lastmod
。
此内容文件的文件系统相关数据。另请参见文件变量(File Variables)。
Fragments返回此页面的片段。请参见页面片段(Page Fragments)。
此内容中字的大致数量。
在 主页(homepage) 的上下文中为 true
。
对于常规内容页面始终为 false
。
对于常规内容页面始终为 true
。
如果 .Kind
是 section
,则为 true
。
如果有要显示的翻译,则为 true
。
此内容的元关键字。
此页面的 kind。可能的返回值为 page
、home
、section
、taxonomy
或 term
。请注意,还有 RSS
、sitemap
、robotsTXT
和 404
类型,但这些仅在每个相应页面类型的渲染期间可用,因此这些不可在任何 Pages
集合中使用。
一个指向该站点 config
中语言定义的语言对象。.Language.Lang
给出语言代码。
此内容最后修改日期。.Lastmod
从内容的前置元数据中的 lastmod
字段获取。
lastmod
并且 .GitInfo
特性已禁用,则将使用前置元数据中的 date
字段。lastmod
并且 .GitInfo
特性已启用,则将使用.GitInfo.AuthorDate
。 另请参阅 .ExpiryDate
、.Date
、.PublishDate
和 .GitInfo。
创建指向此内容的链接时使用。如果设置了(linktitle
),Hugo 将在title
之前使用前置元数据中的 linktitle
。
指向下一个 常规页面(按 Hugo 的 默认排序 排序)。示例:{{ with .Next }}{{ .Permalink }}{{ end }}
。从第一页调用 .Next
将返回 nil
。
指向同一顶级章节的下一个 常规页面(例如在 /blog
中)。页面按 Hugo 的 默认排序 排序。示例:{{ with .NextInSection }}{{ .Permalink }}{{ end }}
。从第一页调用 .NextInSection
将返回 nil
。
包含给定页面的所有格式,包括当前格式。可以与 .Get
函数 结合使用来获取特定格式(请参阅 输出格式)。
相关页面的集合。在常规内容页面的上下文中,此值将为 nil
。请参阅 .Pages。
此页面的永久链接;请参阅 永久链接。
此页面内容去掉 HTML 标签后以字符串形式呈现。在使用 HTML 输出格式 渲染此值时,您可能需要通过 htmlUnescape
函数进行结果处理。
将 .Plain
拆分为字所生成的字符串切片,如 Go 的 strings.Fields 中定义。
指向上一个 常规页面(按 Hugo 的 默认排序 排序)。示例:{{ if .Prev }}{{ .Prev.Permalink }}{{ end }}
。从最后一页调用 .Prev
将返回 nil
。
指向同一顶级章节的下一个 常规页面(例如 /blog
)。页面按 Hugo 的 默认排序 排序。示例:{{ if .PrevInSection }}{{ .PrevInSection.Permalink }}{{ end }}
。从最后一页调用 .PrevInSection
将返回 nil
。
此内容发布日期或将要发布的日期;.Publishdate
从内容的前置元数据中的 publishdate
字段获取。另请参阅 .ExpiryDate
、.Date
和 .Lastmod
。
没有前置元数据的原始Markdown内容。与 remarkjs.com 配合使用很有用。
估计阅读此内容需要的时间(以分钟为单位)。
与此页面相关联的资源,例如图像和CSS。
返回给定引用(例如 .Ref "sample.md"
)的永久链接。.Ref
无法正确处理页面内部片段。请参阅 交叉引用。
此页面的相对永久链接。
返回给定引用(例如 RelRef "sample.md"
)的相对永久链接。.RelRef
无法正确处理页面内部片段。请参阅 交叉引用。
参见站点变量。
返回所有站点(语言)。一个典型的用例是链接回主语言:<a href="{{ .Sites.First.Home.RelPermalink }}">...</a>
。
返回第一种语言的站点。如果这不是多语言设置,则会返回它本身。
此内容的生成摘要,用于在摘要视图中轻松显示片段。可以在内容页中适当位置插入 `
` 来手动设置断点,或者可以独立于页面文本编写摘要。有关详细信息,请参阅 内容摘要。
此页面的渲染 目录。
此页面的标题。
当前页面的翻译版本列表。有关更多信息,请参阅 多语言模式。
用于映射当前页面的语言翻译的key。有关更多信息,请参阅 多语言模式。
一个布尔值,如果 .Summary
被截断,则为 true
。仅在必要时显示"Read more…“链接很有用。有关详细信息,请参阅 摘要。
此内容的 内容类型(例如 posts
)。
分配给此内容的权重(在前置元数据中),用于排序。
此内容中的字数。
另请参见章节。
此页面的当前章节。如果它是一个章节或主页,则该值可以是页面本身。
此页面根目录下的第一个章节,例如 /docs
、/blog
等等。
给定页面是否在当前章节中。
当前页面是否是给定页面的祖先页面。
当前页面是否是给定页面的后代页面。
章节的父级章节或页面所属的章节。
此内容所属的章节。注意: 对于嵌套章节,这是目录中的第一个路径元素,例如 /blog/funny/mypost/ => blog
。
此内容下的章节。
.Pages
变量 .Pages
是 .Data.Pages
的别名。惯例是使用别名形式 .Pages
。
.Pages
与.Site.Pages
的比较常规页面是"post"页面或"content"页面。
列表页面可以列出常规页面和其他列表页面。一些例子是:主页、章节页面、分类法(/tags/
)和条目(/tags/foo/
)页面。
.Site.Pages
站点中所有页面的集合:常规页面、章节、分类法等等。——Superset of everything!
.Site.RegularPages
仅包含常规页面的集合。
上述.Site. ..
页面集合可以从模板的任何作用域中访问。
以下变量仅从当前列表页的作用域返回页面集合:
.Pages
Collection of regular pages and only first-level section pages under the current list page.
在当前列表页面下,包含所有常规页面和只有一级章节页面的集合。
.RegularPages
仅包括当前列表页面下的常规页面的集合。这不包括嵌套章节/列表页面中的常规页面(那些是带有 _index.md
文件的子目录)。
.RegularPagesRecursive
包含一个列表页面下的所有普通页面的集合。这包括嵌套章节/列表页面中的常规页面。
注意
从常规页面的作用域来看,
.Pages
和.RegularPages
返回一个空的 slice。
.Fragments
方法返回当前页面的片段列表。
当前页面的递归标题列表。可用于生成目录。
当前页面的标识符的排序列表。可用于检查页面是否包含特定标识符或页面是否包含重复标识符:
|
|
保存了当前页面的一个标题映射。可用于从特定标题开始生成目录。
还请参阅 Go Doc 获取返回类型的信息。
.Fragments
可以在渲染钩子中安全调用,即使在当前页面(.Page.Fragments
)上也可以。对于简码,我们建议所有 .Fragments
的用法都嵌套在 \{\{\<\>\}\}
简码定界符内(\{\{\%\%\}\}
参与 ToC 的创建,所以很容易陷入一种咬尾巴的情况)。
Hugo 几乎总是将 Page
作为数据上下文传递到顶层模板(例如 single.html
)中(唯一的例外是多主机(multihost )站点地图模板)。这意味着您可以在模板中使用 .
变量访问当前页面。
但是,在 .Render
,partial 等嵌套较深的情况下,访问该 Page
对象并不总是实用或可能的。
因此,Hugo 提供了一个全局的 page
函数,您可以使用它从任何模板中的任何位置访问当前页面。
|
|
这里有一个需要注意的地方,这并不是新问题,但是值得在这里提一下:在 Hugo 中,您可能会看到缓存值的情况,例如在 partialCached
或简码中时。
在内容文件中定义的任何其他值,包括分类法,都将作为 .Params
变量的一部分提供。
content/example.md
=== “yaml”
``` yaml
---
categories:
- one
tags:
- two
- three
- four
title: Example
---
```
=== “toml”
``` toml
+++
categories = ['one']
tags = ['two', 'three', 'four']
title = 'Example'
+++
```
=== “json”
``` json
{
"categories": [
"one"
],
"tags": [
"two",
"three",
"four"
],
"title": "Example"
}
```
使用上面的前置元数据,可以通过以下方式访问 tags
和 categories
分类法:
.Params.tags
.Params.categories
.Params
变量对于在内容文件中引入用户定义的前置元数据字段特别有用。例如,针对图书评论的 Hugo 站点可以具有以下前置元数据:
content/example.md
=== “yaml”
``` yaml
---
affiliatelink: http://www.my-book-link.here
recommendedby: My Mother
title: Example
---
```
=== “toml”
``` toml
+++
affiliatelink = 'http://www.my-book-link.here'
recommendedby = 'My Mother'
title = 'Example'
+++
```
=== “json”
``` json
{
"affiliatelink": "http://www.my-book-link.here",
"recommendedby": "My Mother",
"title": "Example"
}
```
然后可以通过 .Params.affiliatelink
和 .Params.recommendedby
访问这些字段。
|
|
该模板将被渲染成如下:
|
|
有关在每篇内容之间保持 Params
的一致性,请参见 Archetypes。
.Param
方法 在 Hugo 中,您可以针对个别页面和整个站点全局声明参数。一个常见的用例是为站点参数设置一个通用值,为一些页面设置更具体的值(例如,头像图片):
|
|
.Param
方法提供了一种解析单个值的方式,根据它在页面参数(即内容的前置条件)或站点参数(即您的 config
)中的定义。
当前置元数据包含类似以下的嵌套字段时:
content/example.md
=== “yaml”
` yaml
---
author:
display_name: John Feminella
family_name: Feminella
given_name: John
title: Example
---
```
=== “toml”
``` toml
+++
title = 'Example'
[author]
display_name = 'John Feminella'
family_name = 'Feminella'
given_name = 'John'
+++
```
=== “json”
``` json
{
"author": {
"display_name": "John Feminella",
"family_name": "Feminella",
"given_name": "John"
},
"title": "Example"
}
```
.Param
可以通过连接字段名称并用点号分隔来访问这些字段:
|
|
https://gohugo.io/variables/shortcodes/
简码可以访问页面变量,并且有其自己的特定内置变量。
简码通过.Get
访问简码声明中分隔的参数、页面级别和站点级别的变量,还可以访问以下简码特定字段:
简码名称。
与其父简码相对位置的零基序数。如果父简码是页面本身,则该序数将表示页面内容中此简码的位置。
The owning ´Page`.
拥有此简码的页面。
为嵌套简码提供访问父简码上下文的能力。这对于从根继承常见简码参数非常有用。
Contains filename and position for the shortcode in a page. Note that this can be relatively expensive to calculate, and is meant for error reporting. See Error Handling in Shortcodes.
包含页面中此简码的文件名和位置。请注意,这可能是相对昂贵的计算,并且是用于错误报告的。请参见简码错误处理。
返回布尔值,当涉及的简码使用命名参数而不是位置参数时返回true
。
represents the content between the opening and closing shortcode tags when a closing shortcode is used
表示在使用关闭简码时开放和关闭简码标记之间的内容。
返回一个可写的Scratch
,以存储和操作将附加到此简码上下文的数据。此 Scratch 在服务器重新构建时会被重置。
获取任何缩进已删除的.Inner
。这是内置的\{\{\< highlight \>\}\}
简码中使用的内容。
https://gohugo.io/variables/pages/
Pages是Hugo中的核心页面集合,具有许多有用的方法。
此外,请参阅列表模板以获取排序方法的概述。
在Pages
上的.Next
和.Prev
与在.Page
上具有相同名称的方法类似,但更加灵活(并且略微慢一些),因为它们可以用于任何页面集合。
.Next
指向与作为参数发送的页面相对的下一个页面。例如:{{ with .Site.RegularPages.Next . }}{{ .RelPermalink }}{{ end }}
。对集合中的第一个页面调用.Next
将返回nil
。
.Prev
指向与作为参数发送的页面相对的上一个页面。例如:{{ with .Site.RegularPages.Prev . }}{{ .RelPermalink }}{{ end }}
。对集合中的最后一个页面调用.Prev
将返回nil
。
https://gohugo.io/variables/taxonomy/
Hugo 的分类法系统向分类法和条目模板公开了变量。
由分类法模板渲染的页面的 .Kind
设置为 taxonomy
,.Type
设置为分类法名称。
在分类法模板中,您可以访问 .Site
、.Page
、.Section
和 .File
变量,以及以下分类法变量:
分类法的单数形式名称(例如, tags => tag
)。
分类法的复数形式名称(例如, tags => tags
)。
与此分类法相关的条目页面集合。别名为 .Pages
。
一个与此分类法相关的条目和加权页面的映射。
一个与此分类法相关的条目和加权页面的映射,按字母顺序升序排序。使用 .Data.Terms.Alphabetical.Reverse
可以反转排序顺序。
一个与此分类法相关的条目和加权页面的映射,按计数升序排序。使用 .Data.Terms.ByCount.Reverse
可以反转排序顺序。
由条目模板渲染的页面的 .Kind
设置为 term
,.Type
设置为分类法名称。
In term templates you may access .Site
, .Page
. .Section
, and .File
variables, as well as the following term variables:
在分类项模板中,您可以访问 .Site、.Page、.Section 和 .File 变量,以及以下分类项变量:
在分类法条目模板中,您可以访问 .Site
、.Page
、.Section
和 .File
变量,以及以下条目变量:
分类法的单数形式名称(例如 tags => tag
)。
分类法的复数形式名称(例如 tags => tags
)。
与此条目相关的内容页面集合。别名为 .Pages
。
条目本身(例如, tag-one
)。
从任何模板中访问整个分类法数据结构,使用 site.Taxonomies
。这将返回一个包含分类法、条目和与每个条目相关的加权内容页面集合的映射。例如:
|
|
Access a subset of the taxonomy data structure by chaining one or more identifiers, or by using the index
function with one or more keys. For example, to access the collection of weighted content pages related to the news category, use either of the following:
通过链接一个或多个标识符,或使用 index
函数加上一个或多个键,可以访问分类法数据结构的子集。例如,要访问与新闻类别相关的加权内容页面集合,请使用以下任一方法:
|
|
例如,将整个分类法数据结构渲染为嵌套的无序列表:
|
|
有关更多示例,请参见分类法模板。
https://gohugo.io/variables/menus/
在您的菜单模板中使用这些变量和方法。
在定义菜单项之后,可以在菜单模板中使用以下变量访问其属性。
(menu
)当前菜单项下(如果有)的子菜单项的集合。
(string
) 菜单项的 identifier
属性。如果您自动定义菜单项,则为页面的 .Section
。
(string
) 菜单项的 identifier
属性,否则为 name
属性。
(string
) 包含菜单项的菜单的标识符。
(string
) 菜单项的 name
属性。
(page
) 与菜单项相关联的页面的引用。
(map
) 菜单项的 params
属性。
(string
) 菜单项的 parent
属性。
(template.HTML
) 菜单项的 post
属性。
(template.HTML
) 菜单项的 pre
属性。
(string
) 菜单项的 title
属性。
(string
) 与菜单项相关联的页面的 .RelPermalink
。对于指向外部资源的菜单项,使用菜单项的 url
属性。
(int
) 菜单项的 weight
属性。
(bool
) 如果 .Children
非 nil,则返回 true
。
(bool
) 如果比较的菜单项表示相同的菜单项,则返回 true
。
(bool
) 如果比较的菜单条目指向同一资源,则返回true
。
(bool
) 使用此方法确定活动菜单项的祖先。请参阅详细信息。
(bool
) 使用此方法确定活动菜单项。请参阅详细信息。
https://gohugo.io/variables/files/
Use File variables to access file-related values for each page that is backed by a file.
使用文件变量来访问由文件支持的每个页面的与文件相关的值。
使用文件变量来访问每个由文件支持的页面的与文件相关的值。
.File.Path
、.File.Dir
和 .File.Filename
中的路径分隔符(斜杠或反斜杠)取决于操作系统。
(string
) 文件路径,相对于 content
目录。
(string
) 不包括文件名的文件路径,相对于 content
目录。
(string
) 文件名。
(string
) 不包括扩展名的文件名。
(string
) 不包括扩展名和语言标识符的文件名。
(string
) 文件扩展名。
(string
) 与给定文件相关联的语言。
(string
) 如果页面是一个分支或叶子 bundle,则为包含该页面的目录名称,否则为 .TranslationBaseName
。
(string
) 绝对文件路径。
(string
) .File.Path
的 MD5 哈希值。
|
|
使用上述内容结构,英文页面的 .File
对象包含以下属性:
regular content | leaf bundle | branch bundle | |
---|---|---|---|
Path | news/a.en.md | news/b/index.en.md | news/_index.en.md |
Dir | news/ | news/b/ | news/ |
LogicalName | a.en.md | index.en.md | _index.en.md |
BaseFileName | a.en | index.en | _index.en |
TranslationBaseName | a | index | _index |
Ext | md | md | md |
Lang | en | en | en |
ContentBase | a | b | news |
Filename | /home/user/… | /home/user/… | /home/user/… |
UniqueID | 15be14b… | 186868f… | 7d9159d… |
站点上的某些页面可能没有文件支持。例如:
如果您尝试访问 .File
属性而没有支持文件,Hugo 将抛出一个警告。例如:
|
|
为了防御性编程:
|
|
https://gohugo.io/variables/git/
获取每个内容文件的最后一次 Git 修订信息。
Hugo 的 Git 集成应该是相当高效的,但可能会增加构建时间。这取决于您的 Git 历史记录大小。
.GitInfo
先决条件PATH
中。.GitInfo
功能,方法是在命令行上传递 --enableGitInfo
标志或在 站点配置文件 中将 enableGitInfo
设置为 true
。.GitInfo
对象 GitInfo
对象包含以下字段:
缩写的提交哈希(例如 866cbcc
)
作者名称,遵循 .mailmap
作者电子邮件地址,遵循 .mailmap
作者日期。
提交哈希(例如 866cbccdab588b9908887ffd3b4f2667e94090c3
)
提交消息主题(例如, tpl: Add custom index function
)
.Lastmod
如果启用了 .GitInfo
功能,则 .Lastmod
(在 Page
上)从 Git 中获取,即 .GitInfo.AuthorDate
。可以通过添加自己的 日期的前置元数据配置 更改此行为。
https://gohugo.io/variables/sitemap/
sitemap是一个 Page
,因此具有可用于sitemap模板的所有页面变量。 它们还具有以下专门用于sitemap的变量:
页面更改频率
页面的优先级
Sitemap文件名