page.md (11406B)
1 ---
2 title: Page Variables
3 linktitle:
4 description: Page-level variables are defined in a content file's front matter, derived from the content's file location, or extracted from the content body itself.
5 date: 2017-02-01
6 publishdate: 2017-02-01
7 lastmod: 2017-02-01
8 categories: [variables and params]
9 keywords: [pages]
10 draft: false
11 menu:
12 docs:
13 title: "variables defined by a page"
14 parent: "variables"
15 weight: 20
16 weight: 20
17 sections_weight: 20
18 aliases: []
19 toc: true
20 ---
21
22 The following is a list of page-level variables. Many of these will be defined in the front matter, derived from file location, or extracted from the content itself.
23
24 {{% note "`.Scratch`" %}}
25 See [`.Scratch`](/functions/scratch/) for page-scoped, writable variables.
26 {{% /note %}}
27
28 ## Page Variables
29
30 .AlternativeOutputFormats
31 : contains all alternative formats for a given page; this variable is especially useful `link rel` list in your site's `<head>`. (See [Output Formats](/templates/output-formats/).)
32
33 .Aliases
34 : aliases of this page
35
36 .BundleType
37 : the [bundle] type: `leaf`, `branch`, or an empty string if the page is not a bundle.
38
39 .Content
40 : the content itself, defined below the front matter.
41
42 .Data
43 : the data specific to this type of page.
44
45 .Date
46 : the date associated with the page; `.Date` pulls from the `date` field in a content's front matter. See also `.ExpiryDate`, `.PublishDate`, and `.Lastmod`.
47
48 .Description
49 : the description for the page.
50
51 .Draft
52 : a boolean, `true` if the content is marked as a draft in the front matter.
53
54 .ExpiryDate
55 : the date on which the content is scheduled to expire; `.ExpiryDate` pulls from the `expirydate` field in a content's front matter. See also `.PublishDate`, `.Date`, and `.Lastmod`.
56
57 .File
58 : filesystem-related data for this content file. See also [File Variables][].
59
60 .FuzzyWordCount
61 : the approximate number of words in the content.
62
63 .IsHome
64 : `true` in the context of the [homepage](/templates/homepage/).
65
66 .IsNode
67 : always `false` for regular content pages.
68
69 .IsPage
70 : always `true` for regular content pages.
71
72 .IsSection
73 : `true` if [`.Kind`](/templates/section-templates/#page-kinds) is `section`.
74
75 .IsTranslated
76 : `true` if there are translations to display.
77
78 .Keywords
79 : the meta keywords for the content.
80
81 .Kind
82 : the page's *kind*. Possible return values are `page`, `home`, `section`, `taxonomy`, or `term`. Note that there are also `RSS`, `sitemap`, `robotsTXT`, and `404` kinds, but these are only available during the rendering of each of these respective page's kind and therefore *not* available in any of the `Pages` collections.
83
84 .Language
85 : a language object that points to the language's definition in the site `config`. `.Language.Lang` gives you the language code.
86
87 .Lastmod
88 : the date the content was last modified. `.Lastmod` pulls from the `lastmod` field in a content's front matter.
89
90 - If `lastmod` is not set, and `.GitInfo` feature is disabled, the front matter `date` field will be used.
91 - If `lastmod` is not set, and `.GitInfo` feature is enabled, `.GitInfo.AuthorDate` will be used instead.
92
93 See also `.ExpiryDate`, `.Date`, `.PublishDate`, and [`.GitInfo`][gitinfo].
94
95 .LinkTitle
96 : access when creating links to the content. If set, Hugo will use the `linktitle` from the front matter before `title`.
97
98 .Next
99 : Points up to the next [regular page](/variables/site/#site-pages) (sorted by Hugo's [default sort](/templates/lists#default-weight--date--linktitle--filepath)). Example: `{{with .Next}}{{.Permalink}}{{end}}`. Calling `.Next` from the first page returns `nil`.
100
101 .NextInSection
102 : Points up to the next [regular page](/variables/site/#site-pages) below the same top level section (e.g. in `/blog`)). Pages are sorted by Hugo's [default sort](/templates/lists#default-weight--date--linktitle--filepath). Example: `{{with .NextInSection}}{{.Permalink}}{{end}}`. Calling `.NextInSection` from the first page returns `nil`.
103
104 .OutputFormats
105 : contains all formats, including the current format, for a given page. Can be combined the with [`.Get` function](/functions/get/) to grab a specific format. (See [Output Formats](/templates/output-formats/).)
106
107 .Pages
108 : a collection of associated pages. This value will be `nil` within
109 the context of regular content pages. See [`.Pages`](#pages).
110
111 .Permalink
112 : the Permanent link for this page; see [Permalinks](/content-management/urls/)
113
114 .Plain
115 : the Page content stripped of HTML tags and presented as a string.
116
117 .PlainWords
118 : the slice of strings that results from splitting .Plain into words, as defined in Go's [strings.Fields](https://golang.org/pkg/strings/#Fields).
119
120 .Prev
121 : Points down to the previous [regular page](/variables/site/#site-pages) (sorted by Hugo's [default sort](/templates/lists#default-weight--date--linktitle--filepath)). Example: `{{if .Prev}}{{.Prev.Permalink}}{{end}}`. Calling `.Prev` from the last page returns `nil`.
122
123 .PrevInSection
124 : Points down to the previous [regular page](/variables/site/#site-pages) below the same top level section (e.g. `/blog`). Pages are sorted by Hugo's [default sort](/templates/lists#default-weight--date--linktitle--filepath). Example: `{{if .PrevInSection}}{{.PrevInSection.Permalink}}{{end}}`. Calling `.PrevInSection` from the last page returns `nil`.
125
126 .PublishDate
127 : the date on which the content was or will be published; `.Publishdate` pulls from the `publishdate` field in a content's front matter. See also `.ExpiryDate`, `.Date`, and `.Lastmod`.
128
129 .RawContent
130 : raw markdown content without the front matter. Useful with [remarkjs.com](
131 https://remarkjs.com)
132
133 .ReadingTime
134 : the estimated time, in minutes, it takes to read the content.
135
136 .Resources
137 : resources such as images and CSS that are associated with this page
138
139 .Ref
140 : returns the permalink for a given reference (e.g., `.Ref "sample.md"`). `.Ref` does *not* handle in-page fragments correctly. See [Cross References](/content-management/cross-references/).
141
142 .RelPermalink
143 : the relative permanent link for this page.
144
145 .RelRef
146 : returns the relative permalink for a given reference (e.g., `RelRef
147 "sample.md"`). `.RelRef` does *not* handle in-page fragments correctly. See [Cross References](/content-management/cross-references/).
148
149 .Site
150 : see [Site Variables](/variables/site/).
151
152 .Sites
153 : returns all sites (languages). A typical use case would be to link back to the main language: `<a href="{{ .Sites.First.Home.RelPermalink }}">...</a>`.
154
155 .Sites.First
156 : returns the site for the first language. If this is not a multilingual setup, it will return itself.
157
158 .Summary
159 : a generated summary of the content for easily showing a snippet in a summary view. The breakpoint can be set manually by inserting <code><!--more--></code> at the appropriate place in the content page, or the summary can be written independent of the page text. See [Content Summaries](/content-management/summaries/) for more details.
160
161 .TableOfContents
162 : the rendered [table of contents](/content-management/toc/) for the page.
163
164 .Title
165 : the title for this page.
166
167 .Translations
168 : a list of translated versions of the current page. See [Multilingual Mode](/content-management/multilingual/) for more information.
169
170 .TranslationKey
171 : the key used to map language translations of the current page. See [Multilingual Mode](/content-management/multilingual/) for more information.
172
173 .Truncated
174 : a boolean, `true` if the `.Summary` is truncated. Useful for showing a "Read more..." link only when necessary. See [Summaries](/content-management/summaries/) for more information.
175
176 .Type
177 : the [content type](/content-management/types/) of the content (e.g., `posts`).
178
179 .Weight
180 : assigned weight (in the front matter) to this content, used in sorting.
181
182 .WordCount
183 : the number of words in the content.
184
185 ## Section Variables and Methods
186
187 Also see [Sections](/content-management/sections/).
188
189 {{< readfile file="/content/en/readfiles/sectionvars.md" markdown="true" >}}
190
191 ## The `.Pages` Variable {#pages}
192
193 `.Pages` is an alias to `.Data.Pages`. It is conventional to use the
194 aliased form `.Pages`.
195
196 ### `.Pages` compared to `.Site.Pages`
197
198 {{< getcontent path="readfiles/pages-vs-site-pages.md" >}}
199
200 ## Page-level Params
201
202 Any other value defined in the front matter in a content file, including taxonomies, will be made available as part of the `.Params` variable.
203
204 ```
205 ---
206 title: My First Post
207 date: 2017-02-20T15:26:23-06:00
208 categories: [one]
209 tags: [two,three,four]
210 ```
211
212 With the above front matter, the `tags` and `categories` taxonomies are accessible via the following:
213
214 * `.Params.tags`
215 * `.Params.categories`
216
217 {{% note "Casing of Params" %}}
218 Page-level `.Params` are *only* accessible in lowercase.
219 {{% /note %}}
220
221 The `.Params` variable is particularly useful for the introduction of user-defined front matter fields in content files. For example, a Hugo website on book reviews could have the following front matter in `/content/review/book01.md`:
222
223 ```
224 ---
225 ...
226 affiliatelink: "http://www.my-book-link.here"
227 recommendedby: "My Mother"
228 ...
229 ---
230 ```
231
232 These fields would then be accessible to the `/themes/yourtheme/layouts/review/single.html` template through `.Params.affiliatelink` and `.Params.recommendedby`, respectively.
233
234 Two common situations where this type of front matter field could be introduced is as a value of a certain attribute like `href=""` or by itself to be displayed as text to the website's visitors.
235
236 {{< code file="/themes/yourtheme/layouts/review/single.html" >}}
237 <h3><a href={{ printf "%s" $.Params.affiliatelink }}>Buy this book</a></h3>
238 <p>It was recommended by {{ .Params.recommendedby }}.</p>
239 {{< /code >}}
240
241 This template would render as follows, assuming you've set [`uglyURLs`](/content-management/urls/) to `false` in your [site `config`](/getting-started/configuration/):
242
243 {{< output file="yourbaseurl/review/book01/index.html" >}}
244 <h3><a href="http://www.my-book-link.here">Buy this book</a></h3>
245 <p>It was recommended by my Mother.</p>
246 {{< /output >}}
247
248 {{% note %}}
249 See [Archetypes](/content-management/archetypes/) for consistency of `Params` across pieces of content.
250 {{% /note %}}
251
252 ### The `.Param` Method
253
254 In Hugo, you can declare params in individual pages and globally for your entire website. A common use case is to have a general value for the site param and a more specific value for some of the pages (i.e., a header image):
255
256 ```
257 {{ $.Param "header_image" }}
258 ```
259
260 The `.Param` method provides a way to resolve a single value according to it's definition in a page parameter (i.e. in the content's front matter) or a site parameter (i.e., in your `config`).
261
262 ### Access Nested Fields in Front Matter
263
264 When front matter contains nested fields like the following:
265
266 ```
267 ---
268 author:
269 given_name: John
270 family_name: Feminella
271 display_name: John Feminella
272 ---
273 ```
274 `.Param` can access these fields by concatenating the field names together with a dot:
275
276 ```
277 {{ $.Param "author.display_name" }}
278 ```
279
280 If your front matter contains a top-level key that is ambiguous with a nested key, as in the following case:
281
282 ```
283 ---
284 favorites.flavor: vanilla
285 favorites:
286 flavor: chocolate
287 ---
288 ```
289
290 The top-level key will be preferred. Therefore, the following method, when applied to the previous example, will print `vanilla` and not `chocolate`:
291
292 ```
293 {{ $.Param "favorites.flavor" }}
294 => vanilla
295 ```
296
297 [gitinfo]: /variables/git/
298 [File Variables]: /variables/files/
299 [bundle]: {{< relref "content-management/page-bundles" >}}