1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
|
---
title: page
description: Provides global access to a Page object.
categories: []
keywords: []
action:
aliases: []
related:
- functions/global/site
returnType:
signatures: [page]
toc: true
aliases: [/functions/page]
---
{{< new-in 0.111.0 >}}
At the top level of a template that receives a `Page` object in context, these are equivalent:
```go-html-template
{{ .Params.foo }}
{{ .Page.Params.foo }}
{{ page.Params.foo }}
```
When a `Page` object is not in context, you can use the global `page` function:
```go-html-template
{{ page.Params.foo }}
```
{{% note %}}
Do not use the global `page` function in shortcodes, partials called by shortcodes, or cached partials. See [warnings](#warnings) below.
{{% /note %}}
## Explanation
Hugo almost always passes a `Page` as the data context into the top level template (e.g., `single.html`). The one exception is the multihost sitemap template. This means that you can access the current page with the `.` variable in the template.
But when you are deeply nested inside of a [content view], [partial], or [render hook], it is not always practical or possible to access the `Page` object.
Use the global `page` function to access the `Page` object from anywhere in any template.
## Warnings
### Be aware of top-level context
The global `page` function accesses the `Page` object passed into the top-level template.
With this content structure:
```text
content/
├── posts/
│ ├── post-1.md
│ ├── post-2.md
│ └── post-3.md
└── _index.md <-- title is "My Home Page"
```
And this code in the home page template:
```go-html-template
{{ range site.Sections }}
{{ range .Pages }}
{{ page.Title }}
{{ end }}
{{ end }}
```
The rendered output will be:
```text
My Home Page
My Home Page
My Home Page
```
In the example above, the global `page` function accesses the `Page` object passed into the home page template; it does not access the `Page` object of the iterated pages.
### Be aware of caching
Do not use the global `page` function in:
- Shortcodes
- Partials called by shortcodes
- Partials cached by the [`partialCached`] function
Hugo caches rendered shortcodes. If you use the global `page` function within a shortcode, and the page content is rendered in two or more templates, the cached shortcode may be incorrect.
Consider this section template:
```go-html-template
{{ range .Pages }}
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ .Summary }}
{{ end }}
```
When you call the [`Summary`] method, Hugo renders the page content including shortcodes. In this case, within a shortcode, the global `page` function accesses the `Page` object of the section page, not the content page.
If Hugo renders the section page before a content page, the cached rendered shortcode will be incorrect. You cannot control the rendering sequence due to concurrency.
[`Summary`]: /methods/page/summary
[`partialCached`]: /functions/partials/includecached
[content view]: /getting-started/glossary/#content-view
[partial]: /getting-started/glossary/#partial
[render hook]: /getting-started/glossary/#render-hook
[shortcode]: getting-started/glossary/#shortcode
|
