mirror/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2025-08-21 21:35:28 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge commit '35dec7c96f7ee3eb17dd444f7067f0c776fb56ae'

Browse Source
This commit is contained in:
Bjørn Erik Pedersen
2023-12-04 15:24:01 +01:00
parent 9f978d387f 35dec7c96f
commit d19ed4d4e6
810 changed files with 24147 additions and 7766 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
docs/content/en/variables/_common/_index.md Normal file
View File

@@ -0,0 +1,13 @@
---
cascade:
_build:
list: never
publishResources: false
render: never
---
<!--
Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
Include the rendered content using the "include" shortcode.
-->

20
docs/content/en/variables/_common/consistent-terminology.md Normal file
View File

@@ -0,0 +1,20 @@
---
# Do not remove front matter.
---
{{% note %}}
We are making an effort to unify our [terminology], and to use these terms consistently throughout the documentation.
Historically, we have inconsistently referred to the items on this page as [functions], [parameters], [variables], or [methods]. They are not functions, parameters, or variables; they are methods.
This page will remain in place as readers become familiar with the unified terminology. See the [methods section] for a list of methods by [object], or the [methods quick reference guide].
[functions]: /getting-started/glossary/#function
[methods quick reference guide]: /quick-reference/methods
[methods section]: /methods
[methods]: /getting-started/glossary/#method
[object]: /getting-started/glossary/#object
[parameters]: /getting-started/glossary/#parameter
[terminology]: /getting-started/glossary/
[variables]: /getting-started/glossary/#variable
{{% /note %}}

16
docs/content/en/variables/_index.md
View File

@@ -1,18 +1,16 @@
---
title: Variables and parameters
title: Variables
linkTitle: Overview
description: Page-, file-, taxonomy-, and site-level variables and parameters available in templates.
categories: [variables and parameters]
keywords: [variables,params,values,globals]
description: Use these variables in your templates.
categories: []
keywords: []
menu:
docs:
identifier: variables-overview
parent: variables
weight: 1
weight: 1
weight: 10
weight: 10
aliases: [/templates/variables/]
---
Hugo's templates are context aware and make a large number of values available to you as you're creating views for your website.
[Go templates]: /templates/introduction/
{{% include "variables/_common/consistent-terminology.md" %}}

18
docs/content/en/variables/file.md Normal file
View File

@@ -0,0 +1,18 @@
---
title: File variables
description: Retrieve file information about any page that is backed by a file.
categories: [variables]
keywords: []
menu:
docs:
parent: variables
weight: 20
weight: 20
aliases: [/variables/file-variables/,/variables/files/]
---
{{% include "variables/_common/consistent-terminology.md" %}}
To retrieve file information about any page that is backed by a file, see the documentation for the [`File`] method on a `Page` object.
[`File`]: /methods/page/file

102
docs/content/en/variables/files.md
View File

@@ -1,102 +0,0 @@
---
title: File variables
description: "Use File variables to access file-related values for each page that is backed by a file."
categories: [variables and parameters]
keywords: [files]
menu:
docs:
parent: variables
weight: 40
toc: true
weight: 40
aliases: [/variables/file-variables/]
---
## Variables
{{% note %}}
The path separators (slash or backslash) in `.File.Path`, `.File.Dir`, and `.File.Filename` depend on the operating system.
{{% /note %}}
.File.Path
: (`string`) The file path, relative to the `content` directory.
.File.Dir
: (`string`) The file path, excluding the file name, relative to the `content` directory.
.File.LogicalName
: (`string`) The file name.
.File.BaseFileName
: (`string`) The file name, excluding the extension.
.File.TranslationBaseName
: (`string`) The file name, excluding the extension and language identifier.
.File.Ext
: (`string`) The file extension.
.File.Lang
: (`string`) The language associated with the given file.
.File.ContentBaseName
: (`string`) If the page is a branch or leaf bundle, the name of the containing directory, else the `.TranslationBaseName`.
.File.Filename
: (`string`) The absolute file path.
.File.UniqueID
: (`string`) The MD5 hash of `.File.Path`.
## Examples
```text
content/
├── news/
│   ├── b/
│   │   ├── index.de.md <-- leaf bundle
│   │   └── index.en.md <-- leaf bundle
│   ├── a.de.md <-- regular content
│   ├── a.en.md <-- regular content
│   ├── _index.de.md <-- branch bundle
│   └── _index.en.md <-- branch bundle
├── _index.de.md
└── _index.en.md
```
With the content structure above, the `.File` objects for the English pages contain the following properties:
&nbsp;|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
ContentBaseName|a|b|news
Filename|/home/user/...|/home/user/...|/home/user/...
UniqueID|15be14b...|186868f...|7d9159d...
## Defensive coding
Some of the pages on a site may not be backed by a file. For example:
- Top level section pages
- Taxonomy pages
- Term pages
Without a backing file, Hugo will throw a warning if you attempt to access a `.File` property. For example:
```text
WARN .File.ContentBaseName on zero object. Wrap it in if or with...
```
To code defensively:
```go-html-template
{{ with .File }}
{{ .ContentBaseName }}
{{ end }}
```

69
docs/content/en/variables/git.md
View File

@@ -1,71 +1,18 @@
---
title: Git variables
linkTitle: Git variables
description: Get the last Git revision information for every content file.
categories: [variables and parameters]
keywords: [git]
description: Retrieve Git information related to the last commit of any page.
categories: [variables]
keywords: []
menu:
docs:
parent: variables
weight: 70
weight: 70
weight: 30
weight: 30
aliases: [/extras/gitinfo/]
---
{{% note %}}
Hugo's Git integrations should be fairly performant but *can* increase your build time. This will depend on the size of your Git history.
{{% /note %}}
{{% include "variables/_common/consistent-terminology.md" %}}
## `.GitInfo` prerequisites
To retrieve Git information related to the last commit of any page, see the documentation for the [`GitInfo`] method on a `Page` object.
1. The Hugo site must be in a Git-enabled directory.
2. The Git executable must be installed and in your system `PATH`.
3. The `.GitInfo` feature must be enabled in your Hugo project by passing `--enableGitInfo` flag on the command line or by setting `enableGitInfo` to `true` in your [site's configuration file][configuration].
## The `.GitInfo` object
The `GitInfo` object contains the following fields:
.AbbreviatedHash
: the abbreviated commit hash (e.g., `866cbcc`)
.AuthorName
: the author's name, respecting [`.mailmap`](https://git-scm.com/docs/gitmailmap)
.AuthorEmail
: the author's email address, respecting [`.mailmap`](https://git-scm.com/docs/gitmailmap)
.AuthorDate
: the author date
.Hash
: the commit hash (e.g., `866cbccdab588b9908887ffd3b4f2667e94090c3`)
.Subject
: commit message subject (e.g., `tpl: Add custom index function`)
## `.Lastmod`
If the `.GitInfo` feature is enabled, `.Lastmod` (on `Page`) is fetched from Git i.e. `.GitInfo.AuthorDate`. This behavior can be changed by adding your own [front matter configuration for dates](/getting-started/configuration/#configure-front-matter).
[configuration]: /getting-started/configuration/
## Hosting considerations
On the site host, your repository must be "deep-cloned," so the returned `.GitInfo` data will be accurate. Otherwise, your site may display only data from your latest commit. Where it's not possible to configure a host's cloning depth, you must handle this through CI/CD (*e.g.*, a GitHub Action or GitLab CI/CD). See the following table:
| Hosting service | Clone depth | Configurable? |
| :-------------- | :---------- | :-----------: |
| Cloudflare Pages | Shallow | ✔️ [^CFP] |
| DigitalOcean App Platform | Deep | ❌ |
| GitHub Pages | Shallow | ✔️ [^GHP] |
| GitLab Pages | Shallow | ✔️ [^GLP] |
| Netlify | Deep | ❌ |
| Render | Shallow | ❌ |
| Vercel | Shallow | ❌ |
[^CFP]: To configure a Cloudflare Pages site for deep cloning, preface the site's normal Hugo build command with `git fetch --unshallow &&` (*e.g.*, `git fetch --unshallow && hugo`).
[^GHP]: You can configure the GitHub Action to do a deep clone by specifying `fetch-depth: 0` in the applicable "checkout" step of your workflow file, as shown in the Hugo documentation's [example workflow file](/hosting-and-deployment/hosting-on-github/#procedure).
[^GLP]: You can configure the GitLab Runner's clone depth [as explained in the GitLab documentation](https://docs.gitlab.com/ee/ci/large_repositories/#shallow-cloning); see also the Hugo documentation's [example workflow file](https://gohugo.io/hosting-and-deployment/hosting-on-gitlab/#configure-gitlab-cicd).
[`GitInfo`]: /methods/page/gitinfo

16
docs/content/en/variables/menu-entry.md Normal file
View File

@@ -0,0 +1,16 @@
---
title: Menu entry variables
description: Use these methods in your menu templates.
categories: [variables]
keywords: []
menu:
docs:
parent: variables
weight: 40
weight: 40
aliases: [/variables/menus/]
---
{{% include "variables/_common/consistent-terminology.md" %}}
{{< list-pages-in-section path=/methods/menu-entry titlePrefix=. >}}

92
docs/content/en/variables/menus.md
View File

@@ -1,92 +0,0 @@
---
title: Menu variables
description: Use these variables and methods in your menu templates.
categories: [variables and parameters]
keywords: [menus]
menu:
docs:
parent: variables
weight: 50
weight: 50
aliases: [/variables/menu/]
---
## Variables
After [defining menu entries], access their properties in [menu templates] with these variables.
.Children
: (`menu`) A collection of child menu entries, if any, under the current menu entry.
.Identifier
: (`string`) The `identifier` property of the menu entry. If you define the menu entry [automatically], the page's `.Section`.
.KeyName
: (`string`) The `identifier` property of the menu entry, else the `name` property.
.Menu
: (`string`) The identifier of the menu that contains the menu entry.
.Name
: (`string`) The `name` property of the menu entry.
- If you define the menu entry [automatically], the page's `.LinkTitle`, else the page's `.Title`.
- If you define the menu [in front matter] or [in site configuration], falls back to the page's `.LinkTitle`, then to the page's `.Title`.
.Page
: (`page`) A reference to the page associated with the menu entry.
<!-- This provides no value when rendering menu. Omitting to avoid confusion.
.PageRef
: (`string`) The `pageRef` property of the menu entry.
-->
.Params
: (`map`) The `params` property of the menu entry.
.Parent
: (`string`) The `parent` property of the menu entry.
.Post
: (`template.HTML`) The `post` property of the menu entry.
.Pre
: (`template.HTML`) The `pre` property of the menu entry.
.Title
: (`string`) The `title` property of the menu entry.
- If you define the menu entry [automatically], the page's `.LinkTitle`, else the page's `.Title`.
- If you define the menu [in front matter] or [in site configuration], falls back to the page's `.LinkTitle`, then to the page's `.Title`.
.URL
: (`string`) The `.RelPermalink` of the page associated with the menu entry. For menu entries pointing to external resources, the `url` property of the menu entry.
.Weight
: (`int`) The `weight` property of the menu entry.
- If you define the menu entry [automatically], the page's `.Weight`.
- If you define the menu [in front matter] or [in site configuration], falls back to the page's `.Weight`.
## Methods
.HasChildren
: (`bool`) Returns `true` if `.Children` is non-nil.
.IsEqual
: (`bool`) Returns `true` if the compared menu entries represent the same menu entry.
.IsSameResource
: (`bool`) Returns `true` if the compared menu entries point to the same resource.
.Page.HasMenuCurrent
: (`bool`) Use this method to determine ancestors of the active menu entry. See [details](/functions/hasmenucurrent/).
.Page.IsMenuCurrent
: (`bool`) Use this method to determine the active menu entry. See [details](/functions/ismenucurrent/).
[automatically]: /content-management/menus/#define-automatically
[defining menu entries]: /content-management/menus/#overview
[in front matter]: /content-management/menus/#define-in-front-matter
[in site configuration]: /content-management/menus/#define-in-site-configuration
[menu templates]: /templates/menu-templates/

356
docs/content/en/variables/page.md
View File

@@ -1,357 +1,63 @@
---
title: Page variables
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.
categories: [variables and parameters]
keywords: [pages]
description: Use these methods with a Page object.
categories: [variables]
keywords: []
menu:
docs:
parent: variables
weight: 20
weight: 20
weight: 50
weight: 50
toc: true
---
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.
{{% include "variables/_common/consistent-terminology.md" %}}
## Page variables
## All methods
.AlternativeOutputFormats
: 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/).)
Use any of these methods in your templates.
.Aliases
: Aliases of this page
{{< list-pages-in-section path=/methods/page titlePrefix=. >}}
.Ancestors
: Ancestors of this page.
## Dates
.BundleType
: The [bundle] type: `leaf`, `branch`, or an empty string if the page is not a bundle.
Use these methods to access content dates.
.Content
: The content itself, defined below the front matter.
{{< list-pages-in-section path=/methods/page filter=methods_page_dates filterType=include titlePrefix=. omitElementIDs=true >}}
.Data
: The data specific to this type of page.
## Multilingual
.Date
: The date associated with the page. By default, this is the front matter `date` value. See [configuring dates] for a description of fallback values and precedence. See also `.ExpiryDate`, `.Lastmod`, and `.PublishDate`.
Use these methods with your multilingual projects.
.Description
: The description for the page.
{{< list-pages-in-section path=/methods/page filter=methods_page_multilingual filterType=include titlePrefix=. omitElementIDs=true >}}
.Draft
: A boolean, `true` if the content is marked as a draft in the front matter.
## Navigation
.ExpiryDate
: The date on which the content is scheduled to expire. By default, this is the front matter `expiryDate` value. See [configuring dates] for a description of fallback values and precedence. See also `.Date`, `.Lastmod`, and `.PublishDate`.
Use these methods to create navigation links between pages.
.File
: Filesystem-related data for this content file. See also [File Variables].
.Fragments
: Fragments returns the fragments for this page. See [Page Fragments](#page-fragments).
.FuzzyWordCount
: The approximate number of words in the content.
.IsHome
: `true` in the context of the [homepage](/templates/homepage/).
.IsNode
: Always `false` for regular content pages.
.IsPage
: Always `true` for regular content pages.
.IsSection
: `true` if [`.Kind`](/templates/section-templates/#page-kinds) is `section`.
.IsTranslated
: `true` if there are translations to display.
.Keywords
: The meta keywords for the content.
.Kind
: 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.
.Language
: A language object that points to the language's definition in the site configuration. `.Language.Lang` gives you the language code.
.Lastmod
: The date on which the content was last modified. By default, if `enableGitInfo` is `true` in your site configuration, this is the Git author date, otherwise the front matter `lastmod` value. See [configuring dates] for a description of fallback values and precedence. See also `.Date`,`ExpiryDate`, `.PublishDate`, and [`.GitInfo`][gitinfo].
.LinkTitle
: Access when creating links to the content. If set, Hugo will use the `linktitle` from the front matter before `title`.
.Next
: Points up to the next regular page (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`.
.NextInSection
: Points up to the next regular page 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`.
.OutputFormats
: 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/).)
.Permalink
: The Permanent link for this page; see [Permalinks](/content-management/urls/)
.Plain
: The Page content stripped of HTML tags and presented as a string. You may need to pipe the result through the [`htmlUnescape`](/functions/transform/htmlunescape) function when rendering this value with the HTML [output format](/templates/output-formats#output-format-definitions).
.PlainWords
: The slice of strings that results from splitting .Plain into words, as defined in Go's [strings.Fields](https://pkg.go.dev/strings#Fields).
.Prev
: Points down to the previous regular page(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`.
.PrevInSection
: Points down to the previous regular page 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`.
.PublishDate
: The date on which the content was or will be published. By default, this is the front matter `publishDate` value. See [configuring dates] for a description of fallback values and precedence. See also `.Date`, `.ExpiryDate`, and `.Lastmod`.
.RawContent
: Raw markdown content without the front matter. Useful with [remarkjs.com](
https://remarkjs.com)
.RenderShortcodes
: See [Render Shortcodes](#rendershortcodes).
.ReadingTime
: The estimated time, in minutes, it takes to read the content.
.Resources
: Resources such as images and CSS that are associated with this page
.Ref
: 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/).
.RelPermalink
: The relative permanent link for this page.
.RelRef
: Returns the relative permalink for a given reference (e.g., `RelRef
"sample.md"`). `.RelRef` does *not* handle in-page fragments correctly. See [Cross References](/content-management/cross-references/).
.Site
: See [Site Variables](/variables/site/).
.Sites
: Returns all sites (languages). A typical use case would be to link back to the main language: `<a href="{{ .Sites.First.Home.RelPermalink }}">...</a>`.
.Sites.First
: Returns the site for the first language. If this is not a multilingual setup, it will return itself.
.Summary
: A generated summary of the content for easily showing a snippet in a summary view. The breakpoint can be set manually by inserting <code>&lt;!&#x2d;&#x2d;more&#x2d;&#x2d;&gt;</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.
.TableOfContents
: The rendered [table of contents](/content-management/toc/) for the page.
.Title
: The title for this page.
.Translations
: A list of translated versions of the current page. See [Multilingual Mode](/content-management/multilingual/) for more information.
.TranslationKey
: The key used to map language translations of the current page. See [Multilingual Mode](/content-management/multilingual/) for more information.
.Truncated
: 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.
.Type
: The [content type](/content-management/types/) of the content (e.g., `posts`).
.Weight
: Assigned weight (in the front matter) to this content, used in sorting.
.WordCount
: The number of words in the content.
{{< list-pages-in-section path=/methods/page filter=methods_page_navigation filterType=include titlePrefix=. omitElementIDs=true >}}
## Page collections
List pages receive the following page collections in [context](/getting-started/glossary/#context):
Range through these collections when rendering lists on [section] pages, [taxonomy] pages, [term] pages, and the home page.
.Pages
: Regular pages within the current section (not recursive), and section pages for immediate descendant sections (not recursive).
[section]: /getting-started/glossary/#section
[taxonomy]: /getting-started/glossary/#taxonomy
[term]: /getting-started/glossary/#term
[context]: /getting-started/glossary/#context
.RegularPages
: Regular pages within the current section (not recursive).
{{< list-pages-in-section path=/methods/page filter=methods_page_page_collections filterType=include titlePrefix=. omitElementIDs=true >}}
.RegularPagesRecursive
: Regular pages within the current section, and regular pages within all descendant sections.
## Parameters
## Writable page-scoped variables
Use these methods to access page parameters.
[.Scratch][scratch]
: Returns a Scratch to store and manipulate data. In contrast to the [`.Store`][store] method, this scratch is reset on server rebuilds.
{{< list-pages-in-section path=/methods/page filter=methods_page_parameters filterType=include titlePrefix=. omitElementIDs=true >}}
[.Store][store]
: Returns a Scratch to store and manipulate data. In contrast to the [`.Scratch`][scratch] method, this scratch is not reset on server rebuilds.
## Sections
## Section variables and methods
Use these methods to access section pages, and their ancestors and descendants. See&nbsp;[details].
Also see [Sections](/content-management/sections/).
[details]: /content-management/sections/
.CurrentSection
: The page's current section. The value can be the page itself if it is a section or the homepage.
.FirstSection
: The page's first section below root, e.g. `/docs`, `/blog` etc.
.InSection $anotherPage
: Whether the given page is in the current section.
.IsAncestor $anotherPage
: Whether the current page is an ancestor of the given page.
.IsDescendant $anotherPage
: Whether the current page is a descendant of the given page.
.Parent
: A section's parent section or a page's section.
.Section
: The [section](/content-management/sections/) this content belongs to. **Note:** For nested sections, this is the first path element in the directory, for example, `/blog/funny/mypost/ => blog`.
.Sections
: The [sections](/content-management/sections/) below this content.
## Page fragments
{{< new-in "0.111.0" >}}
The `.Fragments` method returns a list of fragments for the current page.
.Headings
: A recursive list of headings for the current page. Can be used to generate a table of contents.
{{< todo >}}add .Headings toc example{{< /todo >}}
.Identifiers
: A sorted list of identifiers for the current page. Can be used to check if a page contains a specific identifier or if a page contains duplicate identifiers:
```go-html-template
{{ if .Fragments.Identifiers.Contains "my-identifier" }}
<p>Page contains identifier "my-identifier"</p>
{{ end }}
{{ if gt (.Fragments.Identifiers.Count "my-identifier") 1 }}
<p>Page contains duplicate "my-identifier" fragments</p>
{{ end }}
```
.HeadingsMap
: Holds a map of headings for the current page. Can be used to start the table of contents from a specific heading.
Also see the [Go Doc](https://pkg.go.dev/github.com/gohugoio/hugo@v0.111.0/markup/tableofcontents#Fragments) for the return type.
### Fragments in hooks and shortcodes
`.Fragments` are safe to call from render hooks, even on the page you're on (`.Page.Fragments`). For shortcodes we recommend that all `.Fragments` usage is nested inside the `{{</**/>}}` shortcode delimiter (`{{%/**/%}}` takes part in the ToC creation so it's easy to end up in a situation where you bite yourself in the tail).
## The `.RenderShortcodes` method {#rendershortcodes}
{{< new-in "0.117.0" >}} This renders all the shortcodes in the content, preserving the surrounding markup (e.g. Markdown) as is.
The common use case this is to composing a page from multiple content files while preserving a global context for table of contents and foot notes.
This method is most often used in shortcode templates. A simple example of shortcode template including content from another page would look like:
```go-html-template
{{ $p := site.GetPage (.Get 0) }}
{{ $p.RenderShortcodes }}
```
In the above it's important to understand and the difference between the two delimiters used when including a shortcode:
* `{{</* myshortcode */>}}` tells Hugo that the rendered shortcode does not need further processing (e.g. it's HTML).
* `{{%/* myshortcode */%}}` tells Hugo that the rendered shortcode needs further processing (e.g. it's Markdown).
The latter is what you want to use for the include shortcode outlined above:
```md
## Mypage
{{%/* include "mypage" */%}}
``````
Also see [Use Shortcodes](/content-management/shortcodes/#use-shortcodes).
## Page-level params
Any other value defined in the front matter in a content file, including taxonomies, will be made available as part of the `.Params` variable.
{{< code-toggle file="content/example.md" fm=true copy=false >}}
title: Example
categories: [one]
tags: [two,three,four]
{{< /code-toggle >}}
With the above front matter, the `tags` and `categories` taxonomies are accessible via the following:
* `.Params.tags`
* `.Params.categories`
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:
{{< code-toggle file="content/example.md" fm=true copy=false >}}
title: Example
affiliatelink: "http://www.my-book-link.here"
recommendedby: "My Mother"
{{< /code-toggle >}}
These fields would then be accessible to via `.Params.affiliatelink` and `.Params.recommendedby`.
```go-html-template
<h3><a href="{{ .Params.affiliatelink }}">Buy this book</a></h3>
<p>It was recommended by {{ .Params.recommendedby }}.</p>
```
This template would render as follows:
```html
<h3><a href="http://www.my-book-link.here">Buy this book</a></h3>
<p>It was recommended by my Mother.</p>
```
{{% note %}}
See [Archetypes](/content-management/archetypes/) for consistency of `Params` across pieces of content.
{{% /note %}}
### The `.Param` method
In Hugo, you can declare parameters in individual pages and globally for your entire website. A common use case is to have a general value for the site parameter and a more specific value for some of the pages (i.e., a header image):
```go-html-template
{{ $.Param "header_image" }}
```
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 site configuration).
### Access nested fields in front matter
When front matter contains nested fields like the following:
{{< code-toggle file="content/example.md" fm=true copy=false >}}
title: Example
author:
given_name: John
family_name: Feminella
display_name: John Feminella
{{< /code-toggle >}}
`.Param` can access these fields by concatenating the field names together with a dot:
```go-html-template
{{ $.Param "author.display_name" }}
```
[configuring dates]: /getting-started/configuration/#configure-dates
[gitinfo]: /variables/git/
[File Variables]: /variables/files/
[bundle]: /content-management/page-bundles
[scratch]: /functions/scratch
[store]: /functions/store
{{< list-pages-in-section path=/methods/page filter=methods_page_sections filterType=include titlePrefix=. omitElementIDs=true >}}

40
docs/content/en/variables/pages.md
View File

@@ -1,25 +1,39 @@
---
title: Pages methods
description: Pages is the core page collection in Hugo and has many useful methods.
categories: [variables and parameters]
keywords: [pages]
title: Pages variables
description: Use these methods with a collection of Page objects.
categories: [variables]
keywords: []
menu:
docs:
parent: variables
weight: 21
weight: 21
aliases: [/pages]
weight: 60
weight: 60
toc: true
aliases: [/variables/site-variables/]
---
Also see [List templates](/templates/lists) for an overview of sort methods.
{{% include "variables/_common/consistent-terminology.md" %}}
## .Next PAGE
## All methods
`.Next` and `.Prev` on `Pages` work similar to the methods with the same names on `.Page`, but are more flexible (and slightly slower) as they can be used on any page collection.
Use any of these methods with page collections in your templates.
`.Next` points **up** to the next page relative to the page sent in as the argument. Example: `{{ with .Site.RegularPages.Next . }}{{ .RelPermalink }}{{ end }}`. Calling `.Next` with the first page in the collection returns `nil`.
{{< list-pages-in-section path=/methods/pages titlePrefix=. >}}
## .Prev PAGE
## Sort by
`.Prev` points **down** to the previous page relative to the page sent in as the argument. Example: `{{ with .Site.RegularPages.Prev . }}{{ .RelPermalink }}{{ end }}`. Calling `.Prev` with the last page in the collection returns `nil`.
Use these methods to sort page collections.
{{< list-pages-in-section path=/methods/pages filter=methods_pages_sort filterType=include titlePrefix=. omitElementIDs=true >}}
## Group by
Use these methods to group page collections.
{{< list-pages-in-section path=/methods/pages filter=methods_pages_group filterType=include titlePrefix=. omitElementIDs=true >}}
## Navigation
Use these methods to create navigation links between pages.
{{< list-pages-in-section path=/methods/pages filter=methods_pages_navigation filterType=include titlePrefix=. omitElementIDs=true >}}

16
docs/content/en/variables/shortcode.md Normal file
View File

@@ -0,0 +1,16 @@
---
title: Shortcode variables
description: Use these methods in your shortcode templates.
categories: [variables]
keywords: []
menu:
docs:
parent: variables
weight: 70
weight: 70
aliases: [/variables/shortcodes]
---
{{% include "variables/_common/consistent-terminology.md" %}}
{{< list-pages-in-section path=/methods/shortcode titlePrefix=. >}}

45
docs/content/en/variables/shortcodes.md
View File

@@ -1,45 +0,0 @@
---
title: Shortcode variables
description: Shortcodes can access page variables and also have their own specific built-in variables.
categories: [variables and parameters]
keywords: [shortcodes]
menu:
docs:
parent: variables
weight: 20
weight: 20
---
[Shortcodes][shortcodes] have access to parameters delimited in the shortcode declaration via [`.Get`][getfunction], page- and site-level variables, and also the following shortcode-specific fields:
.Name
: Shortcode name.
.Ordinal
: Zero-based ordinal in relation to its parent. If the parent is the page itself, this ordinal will represent the position of this shortcode in the page content.
.Page
: The owning ´Page`.
.Parent
: provides access to the parent shortcode context in nested shortcodes. This can be very useful for inheritance of common shortcode parameters from the root.
.Position
: Contains [file name and position](https://godoc.org/github.com/gohugoio/hugo/common/text#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](/templates/shortcode-templates/#error-handling-in-shortcodes).
.IsNamedParams
: boolean that returns `true` when the shortcode in question uses [named rather than positional parameters][shortcodes]
.Inner
: represents the content between the opening and closing shortcode tags when a [closing shortcode][markdownshortcode] is used
.Scratch
: returns a writable [`Scratch`][scratch] to store and manipulate data which will be attached to the shortcode context. This scratch is reset on server rebuilds.
.InnerDeindent {{< new-in "0.100.0" >}}
: Gets the `.Inner` with any indentation removed. This is what's used in the built-in `{{</* highlight */>}}` shortcode.
[getfunction]: /functions/get/
[markdownshortcode]: /content-management/shortcodes/#shortcodes-with-markdown
[shortcodes]: /templates/shortcode-templates/
[scratch]: /functions/scratch

115
docs/content/en/variables/site.md
View File

@@ -1,108 +1,55 @@
---
title: Site variables
description: Many, but not all, site-wide variables are defined in your site's configuration. However, Hugo provides a number of built-in variables for convenient access to global values in your templates.
categories: [variables and parameters]
keywords: [global,site]
description: Use these methods with Site objects. A multilingual project will have two or more sites, one for each language.
categories: [variables]
keywords: []
menu:
docs:
parent: variables
weight: 10
weight: 10
aliases: [/variables/site-variables/]
weight: 80
weight: 80
toc: true
aliases: [/variables/site-variables/]
---
The following is a list of site-level (aka "global") variables. Many of these variables are defined in your site's [configuration file][config], whereas others are built into Hugo's core for convenient usage in your templates.
{{% include "variables/_common/consistent-terminology.md" %}}
## Get the site object from a partial
## All methods
All the methods below, e.g. `.Site.RegularPages` can also be reached via the global [`site`](/functions/site/) function, e.g. `site.RegularPages`, which can be handy in partials where the `Page` object isn't easily available.
Use any of these methods in your templates.
## Site variables
{{< list-pages-in-section path=/methods/site titlePrefix=.Site. >}}
.Site.AllPages
: array of all pages, regardless of their translation.
## Multilingual
.Site.BaseURL
: the base URL for the site as defined in the site configuration.
Use these methods with your multilingual projects.
.Site.BuildDrafts
: a boolean (default: `false`) to indicate whether to build drafts as defined in the site configuration.
{{< list-pages-in-section path=/methods/site filter=methods_site_multilingual filterType=include titlePrefix=.Site. omitElementIDs=true >}}
.Site.Copyright
: a string representing the copyright of your website as defined in the site configuration.
[`site`]: /functions/global/site
[context]: /getting-started/glossary/#context
[configuration file]: /getting-started/configuration
.Site.Data
: custom data, see [Data Templates](/templates/data-templates/).
## Page collections
.Site.Home
: reference to the homepage's [page object](/variables/page/)
Range through these collections when rendering lists on any page.
.Site.IsMultiLingual
: whether there are more than one language in this site. See [Multilingual](/content-management/multilingual/) for more information.
{{< list-pages-in-section path=/methods/site filter=methods_site_page_collections filterType=include titlePrefix=.Site. omitElementIDs=true >}}
.Site.Language.Lang
: the language code of the current locale (e.g., `en`).
## Global site function
.Site.Language.LanguageName
: the full language name (e.g. `English`).
Within a partial template, if you did not pass a `Page` or `Site` object in [context], you cannot use this syntax:
.Site.Language.Weight
: the weight that defines the order in the `.Site.Languages` list.
```go-html-template
{{ .Site.SomeMethod }}
```
.Site.Language
: indicates the language currently being used to render the website. This object's attributes are set in site configurations' language definition.
Instead, use the global [`site`] function:
.Site.LanguageCode
: a string representing the language tag as defined in the site configuration.
```go-html-template
{{ site.SomeMethod }}
```
.Site.LanguagePrefix
: this can be used to prefix URLs to point to the correct language. It will even work when there is only one defined language. See also the functions [absLangURL](/functions/urls/abslangurl) and [relLangURL](/functions/urls/rellangurl).
.Site.Languages
: an ordered list (ordered by defined weight) of languages.
.Site.LastChange
: a [time.Time](https://godoc.org/time#Time) value representing the date/time of the most recent change to your site.
.Site.Menus
: all the menus in the site.
.Site.Pages
: array of all content ordered by Date with the newest first. This array contains only the pages in the current language.
.Site.RegularPages
: a shortcut to the *regular* page collection. `.Site.RegularPages` is equivalent to `where .Site.Pages "Kind" "page"`.
.Site.Sections
: top-level directories of the site.
.Site.Taxonomies
: the [taxonomies](/content-management/taxonomies/) for the entire site. Also see section [Access taxonomy data from any template](/variables/taxonomy/#access-taxonomy-data-from-any-template).
.Site.Title
: a string representing the title of the site.
## Site parameters
`.Site.Params` is a container holding the values from the `params` section of your site configuration.
### Example: `.Site.Params`
The following `config.[yaml|toml|json]` defines a site-wide parameter for `description`:
{{< code-toggle file="hugo" >}}
baseURL = "https://yoursite.example.com/"
[params]
description = "Tesla's Awesome Hugo Site"
author = "Nikola Tesla"
{{</ code-toggle >}}
You can use `.Site.Params` in a [partial template](/templates/partials/) to call the default site description:
{{< code file="layouts/partials/head.html" >}}
<meta name="description" content="{{ if .IsHome }}{{ $.Site.Params.description }}{{ else }}{{ .Description }}{{ end }}" />
{{< /code >}}
[config]: /getting-started/configuration/
{{% note %}}
You can use the global site function in all templates to avoid context problems. Its usage is not limited to partial templates.
{{% /note %}}

24
docs/content/en/variables/sitemap.md
View File

@@ -1,24 +0,0 @@
---
title: Sitemap variables
description:
categories: [variables and parameters]
keywords: [sitemap]
menu:
docs:
parent: variables
weight: 80
weight: 80
---
A sitemap is a `Page` and therefore has all the [page variables][pagevars] available to use sitemap templates. They also have the following sitemap-specific variables available to them:
.Sitemap.ChangeFreq
: the page change frequency
.Sitemap.Priority
: the priority of the page
.Sitemap.Filename
: the sitemap file name
[pagevars]: /variables/page/

139
docs/content/en/variables/taxonomy.md
View File

@@ -1,138 +1,21 @@
---
title: Taxonomy variables
description: Hugo's taxonomy system exposes variables to taxonomy and term templates.
categories: [variables and parameters]
keywords: [taxonomy,term]
description: Use these methods with Taxonomy objects.
categories: [variables]
keywords: []
menu:
docs:
parent: variables
weight: 30
toc: true
weight: 30
weight: 90
weight: 90
---
## Taxonomy templates
{{% include "variables/_common/consistent-terminology.md" %}}
Pages rendered by taxonomy templates have `.Kind` set to `taxonomy` and `.Type` set to the taxonomy name.
{{< list-pages-in-section path=/methods/taxonomy titlePrefix=. >}}
In taxonomy templates you may access `.Site`, `.Page`. `.Section`, and `.File` variables, as well as the following _taxonomy_ variables:
{{% note %}}
Within a taxonomy or term template use the [`Data`] method to retrieve information specific to the taxonomy or term.
.Data.Singular
: The singular name of the taxonomy (e.g., `tags => tag`).
.Data.Plural
: The plural name of the taxonomy (e.g., `tags => tags`).
.Data.Pages
: The collection of term pages related to this taxonomy. Aliased by `.Pages`.
.Data.Terms
: A map of terms and weighted pages related to this taxonomy.
.Data.Terms.Alphabetical
: A map of terms and weighted pages related to this taxonomy, sorted alphabetically in ascending order. Reverse the sort order with`.Data.Terms.Alphabetical.Reverse`.
.Data.Terms.ByCount
: A map of terms and weighted pages related to this taxonomy, sorted by count in ascending order. Reverse the sort order with`.Data.Terms.ByCount.Reverse`.
## Term templates
Pages rendered by term templates have `.Kind` set to `term` and `.Type` set to the taxonomy name.
In term templates you may access `.Site`, `.Page`. `.Section`, and `.File` variables, as well as the following _term_ variables:
.Data.Singular
: The singular name of the taxonomy (e.g., `tags => tag`).
.Data.Plural
: The plural name of the taxonomy (e.g., `tags => tags`).
.Data.Pages
: The collection of content pages related to this taxonomy. Aliased by `.Pages`.
.Data.Term
: The term itself (e.g., `tag-one`).
## Access taxonomy data from any template
Access the entire taxonomy data structure from any template with `site.Taxonomies`. This returns a map of taxonomies, terms, and a collection of weighted content pages related to each term. For example:
```json
{
"categories": {
"news": [
{
"Weight": 0,
"Page": {
"Title": "Post 1",
"Date": "2022-12-18T15:13:35-08:00"
...
}
},
{
"Weight": 0,
"Page": {
"Title": "Post 2",
"Date": "2022-12-18T15:13:46-08:00",
...
}
}
]
},
"tags": {
"international": [
{
"Weight": 0,
"Page": {
"Title": "Post 1",
"Date": "2021-01-01T00:00:00Z"
...
}
}
]
}
}
```
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`]: /functions/collections/indexfunction/
```go-html-template
{{ $pages := site.Taxonomies.categories.news }}
{{ $pages := index site.Taxonomies "categories" "news" }}
```
For example, to render the entire taxonomy data structure as a nested unordered list:
```go-html-template
<ul>
{{ range $taxonomy, $terms := site.Taxonomies }}
<li>
{{ with site.GetPage $taxonomy }}
<a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
{{ end }}
<ul>
{{ range $term, $weightedPages := $terms }}
<li>
{{ with site.GetPage (path.Join $taxonomy $term) }}
<a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
{{ end }}
</li>
<ul>
{{ range $weightedPages }}
<li>
<a href="{{ .RelPermalink }}"> {{ .LinkTitle }}</a>
</li>
{{ end }}
</ul>
{{ end }}
</ul>
</li>
{{ end }}
</ul>
```
See [Taxonomy Templates] for more examples.
[Taxonomy Templates]: /templates/taxonomy-templates/
[`Data`]: /methods/page/data
{{% /note %}}